Skip to content

Commit 13ff9df

Browse files
QG-phyQG-phy
authored
CI: add maintainer review governance safeguards (#337)
* docs: add maintainer review governance guidance * ci: add repository hygiene and PR review plan automation * test: add pytest review markers * docs: triage low-risk Sphinx warnings * github: collect review context in issue templates * ci: address review feedback on helper scripts
1 parent fb7db07 commit 13ff9df

40 files changed

Lines changed: 1551 additions & 10 deletions

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,40 @@ body:
1414
validations:
1515
required: true
1616

17+
- type: dropdown
18+
attributes:
19+
label: Affected area
20+
description: Pick the area closest to the failure. Use Additional Context if multiple areas are involved.
21+
options:
22+
- Config / argcheck
23+
- AtomicData / dataset
24+
- OrbitalMapper / basis indexing
25+
- Hamiltonian / overlap
26+
- Model build / checkpoint
27+
- Training / loss
28+
- CLI / entrypoint
29+
- Postprocess / export
30+
- Documentation / examples
31+
- Other
32+
33+
- type: textarea
34+
attributes:
35+
label: Config, data, or checkpoint involved
36+
description: |
37+
Link or paste the relevant config path, dataset type/path, checkpoint path, and whether the failure depends on a specific dtype/device.
38+
1739
- type: textarea
1840
attributes:
1941
label: Expected behavior
2042
description: |
2143
A clear and concise description of what you expected to happen.
2244
45+
- type: textarea
46+
attributes:
47+
label: Expected vs actual numerical behavior
48+
description: |
49+
For numerical issues, describe expected values, actual values, tolerances, shapes, ordering, units, or whether the difference is systematic/random.
50+
2351
- type: textarea
2452
attributes:
2553
label: To Reproduce
@@ -31,6 +59,12 @@ body:
3159
3260
It is recommended to attach your calculation case here for the developers to reproduce the bug.
3361
62+
- type: textarea
63+
attributes:
64+
label: Minimal reproduction
65+
description: |
66+
Provide the smallest command, config, structure, or snippet that reproduces the issue. If a full dataset is required, explain why.
67+
3468
- type: textarea
3569
attributes:
3670
label: Environment

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,16 @@ body:
1212
Example: The documentation for the band structure calculations is missing. I have read the online manual, but I am still not sure how to do it. My suggestion is to add a new section to the online manual that describes this.
1313
validations:
1414
required: true
15+
- type: textarea
16+
attributes:
17+
label: Affected command, config, or example path
18+
description: |
19+
Include the command, config option, example file, docs path, or notebook path related to this documentation issue.
20+
- type: textarea
21+
attributes:
22+
label: Behavior mismatch
23+
description: |
24+
If the docs disagree with current behavior, describe what the docs say and what DeePTB actually does.
1525
- type: markdown
1626
attributes:
1727
value: >

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,21 @@ body:
1212
validations:
1313
required: true
1414

15+
- type: dropdown
16+
attributes:
17+
label: Affected area
18+
description: Pick the area that would most likely need implementation or review.
19+
options:
20+
- Model / Hamiltonian
21+
- Data / AtomicData
22+
- Config schema
23+
- CLI / workflow
24+
- Training / loss
25+
- Postprocess / export
26+
- Plugin / integration
27+
- Documentation / examples
28+
- Other
29+
1530
- type: textarea
1631
attributes:
1732
label: Describe the solution you'd like
@@ -20,6 +35,18 @@ body:
2035
validations:
2136
required: true
2237

38+
- type: textarea
39+
attributes:
40+
label: Compatibility expectations
41+
description: |
42+
Describe whether this should preserve existing API, CLI, config, checkpoint, dataset, or output-format behavior.
43+
44+
- type: textarea
45+
attributes:
46+
label: Test or example expectations
47+
description: |
48+
Describe the expected smoke/regression/slow tests or runnable examples that should cover this feature.
49+
2350
- type: textarea
2451
attributes:
2552
label: Additional Context
@@ -29,4 +56,4 @@ body:
2956
- type: markdown
3057
attributes:
3158
value: >
32-
Thanks for contributing 🎉!
59+
Thanks for contributing 🎉!

‎.github/ISSUE_TEMPLATE/tests.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,36 @@ body:
1111
validations:
1212
required: true
1313

14+
- type: dropdown
15+
attributes:
16+
label: Target pytest marker
17+
description: Choose the intended test layer from docs/maintenance/test_strategy.md.
18+
options:
19+
- smoke
20+
- regression
21+
- slow
22+
- unmarked / exploratory
23+
24+
- type: dropdown
25+
attributes:
26+
label: Risk area
27+
description: Choose the closest area from docs/maintenance/risk_map.md.
28+
options:
29+
- AtomicDataDict contract
30+
- Orbital indexing
31+
- Hamiltonian expansion
32+
- Model assembly
33+
- Config schema
34+
- Training behavior
35+
- Loss behavior
36+
- Embedding and prediction
37+
- Dataset backends
38+
- CLI entrypoints
39+
- Postprocess and export
40+
- Plugins
41+
- Documentation / examples
42+
- Other
43+
1444
- type: textarea
1545
attributes:
1646
label: Additional Context

‎.github/pull_request_template.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
## Scope
2+
3+
Briefly describe what this PR changes and why.
4+
5+
## DeePTB Impact Area
6+
7+
Check every area that may be affected, even indirectly.
8+
9+
- [ ] AtomicData / dataset loading
10+
- [ ] AtomicDataDict keys or tensor semantics
11+
- [ ] OrbitalMapper / basis-to-index mapping
12+
- [ ] Hamiltonian / overlap construction
13+
- [ ] Model build / checkpoint loading
14+
- [ ] NNENV / NNSK / DFTBSK / MIX behavior
15+
- [ ] Config schema / defaults / examples
16+
- [ ] Training / testing / loss behavior
17+
- [ ] CLI / postprocess / export
18+
- [ ] Documentation only
19+
20+
## Risk And Compatibility
21+
22+
- Risk level: low / medium / high
23+
- Public API changed: yes / no
24+
- CLI behavior changed: yes / no
25+
- Config schema changed: yes / no
26+
- Checkpoint compatibility affected: yes / no
27+
- Dataset format compatibility affected: yes / no
28+
29+
If any answer is "yes", explain the intended compatibility behavior.
30+
31+
## Tests
32+
33+
List the tests you ran and the behavior they cover.
34+
35+
```bash
36+
37+
```
38+
39+
## AI Assistance
40+
41+
- [ ] This PR used AI assistance for code, tests, docs, or review.
42+
- [ ] AI-generated changes were manually checked for DeePTB domain correctness.
43+
- [ ] AI review findings were handled or explicitly waived below.
44+
45+
Notes:
46+
47+
## Merge Decision
48+
49+
For maintainers. Fill this before merging.
50+
51+
- Recommendation: merge / merge after fixes / hold
52+
- Remaining risks:
53+
- Known limitations:
54+
- Follow-up issue needed: yes / no
55+

‎.github/workflows/pr_review_plan.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: PR Review Plan
2+
3+
on:
4+
pull_request:
5+
6+
jobs:
7+
review-plan:
8+
name: Generate advisory PR review plan
9+
runs-on: ubuntu-latest
10+
permissions:
11+
contents: read
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
with:
16+
fetch-depth: 0
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.11"
22+
23+
- name: Compute changed files
24+
run: |
25+
git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" > changed-files.txt
26+
27+
- name: Generate review plan
28+
run: |
29+
python scripts/ci/pr_review_plan.py --stdin < changed-files.txt > pr-review-plan.md
30+
cat pr-review-plan.md >> "$GITHUB_STEP_SUMMARY"

‎.github/workflows/pr_review_plan_comment.yml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
name: PR Review Plan Comment
2+
3+
on:
4+
pull_request_target:
5+
types: [opened, synchronize, reopened]
6+
7+
jobs:
8+
review-plan-comment:
9+
name: Comment advisory PR review plan
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: read
13+
pull-requests: read
14+
issues: write
15+
steps:
16+
- name: Checkout trusted base code
17+
uses: actions/checkout@v4
18+
with:
19+
ref: ${{ github.event.pull_request.base.sha }}
20+
21+
- name: Set up Python
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.11"
25+
26+
- name: Get changed files
27+
uses: actions/github-script@v7
28+
with:
29+
script: |
30+
const files = await github.paginate(
31+
github.rest.pulls.listFiles,
32+
{
33+
owner: context.repo.owner,
34+
repo: context.repo.repo,
35+
pull_number: context.payload.pull_request.number,
36+
per_page: 100,
37+
}
38+
);
39+
const names = files.map((file) => file.filename).join("\n");
40+
require("fs").writeFileSync("changed-files.txt", names);
41+
42+
- name: Generate review plan
43+
run: |
44+
python scripts/ci/pr_review_plan.py --stdin < changed-files.txt > pr-review-plan.md
45+
46+
- name: Comment review plan
47+
uses: actions/github-script@v7
48+
with:
49+
script: |
50+
const fs = require("fs");
51+
const marker = "<!-- deeptb-pr-review-plan -->";
52+
const plan = fs.readFileSync("pr-review-plan.md", "utf8");
53+
const body = [
54+
marker,
55+
"This advisory review plan was generated from changed file names using trusted base-branch code.",
56+
"",
57+
plan,
58+
].join("\n");
59+
60+
const comments = await github.paginate(
61+
github.rest.issues.listComments,
62+
{
63+
owner: context.repo.owner,
64+
repo: context.repo.repo,
65+
issue_number: context.payload.pull_request.number,
66+
per_page: 100,
67+
}
68+
);
69+
70+
const previous = comments.find((comment) =>
71+
comment.user.type === "Bot" && comment.body.includes(marker)
72+
);
73+
74+
if (previous) {
75+
await github.rest.issues.updateComment({
76+
owner: context.repo.owner,
77+
repo: context.repo.repo,
78+
comment_id: previous.id,
79+
body,
80+
});
81+
} else {
82+
await github.rest.issues.createComment({
83+
owner: context.repo.owner,
84+
repo: context.repo.repo,
85+
issue_number: context.payload.pull_request.number,
86+
body,
87+
});
88+
}

‎.github/workflows/repository_hygiene.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Repository Hygiene
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- '.github/**'
7+
- 'docs/**'
8+
- 'examples/**'
9+
- 'CONTEXT.md'
10+
- 'scripts/ci/**'
11+
push:
12+
branches: [ main ]
13+
paths:
14+
- '.github/**'
15+
- 'docs/**'
16+
- 'examples/**'
17+
- 'CONTEXT.md'
18+
- 'scripts/ci/**'
19+
20+
jobs:
21+
hygiene:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- name: Checkout
25+
uses: actions/checkout@v6
26+
27+
- name: Set up Python
28+
uses: actions/setup-python@v6
29+
with:
30+
python-version: '3.11'
31+
32+
- name: Check repository hygiene
33+
run: python scripts/ci/check_repository_hygiene.py
34+

0 commit comments

Comments
 (0)