PR Review Plan

PR Review Plan#

scripts/ci/pr_review_plan.py turns changed files into an advisory review plan. It is the active counterpart to the maintainer SOP: instead of expecting the maintainer to remember every rule, it prints the likely risk level, review focus, AI prompt suggestions, tests, and hold conditions.

The script is stdlib-only and does not call GitHub, AI services, or DeePTB runtime dependencies.

Local Usage#

Pass files directly:

python scripts/ci/pr_review_plan.py --changed-files dptb/nn/hamiltonian.py

Or pipe changed files from git:

git diff --name-only main...HEAD | python scripts/ci/pr_review_plan.py --stdin

The output is Markdown and can be pasted into a PR’s AI Assistance or Merge Decision notes.

For a shorter PR-page comment format, use:

git diff --name-only main...HEAD | python scripts/ci/pr_review_plan.py --stdin --format github-comment

The default CLI format is intentionally detailed. The GitHub comment format is optimized for maintainer scanning: the visible summary is bilingual, while detailed file lists, local commands, and hold conditions are kept in collapsible sections.

GitHub Automation#

DeePTB has two advisory workflows for this plan:

  • .github/workflows/pr_review_plan.yml runs on pull_request and writes the plan to the Actions job summary.

  • .github/workflows/pr_review_plan_comment.yml runs on pull_request_target and writes or updates one PR comment.

The comment workflow is designed for fork PRs. It checks out the trusted base commit from the main repository, reads changed file names through the GitHub API, then runs the base-branch copy of scripts/ci/pr_review_plan.py. It must not checkout or execute code from the fork branch.

The comment workflow may also add an Evidence section based on GitHub check status. That evidence is owned by the workflow, not by pr_review_plan.py, because the script only knows changed file names.

Required permissions for the comment workflow are intentionally narrow:

permissions:
  contents: read
  pull-requests: write
  issues: write

issues: write is needed because PR timeline comments use the issues comments API. pull-requests: write is needed for repositories where GitHub requires both issue-comment and pull-request write scopes for PR timeline comments. The workflow updates the existing bot comment using a hidden marker instead of creating a new comment on every PR update.

How To Read The Output#

  • Risk level follows docs/maintenance/risk_map.md.

  • Touched risk areas show which mapped areas were changed.

  • Required maintainer focus lists what a human should inspect.

  • Suggested AI review points to the minimum recommended prompts.

  • Suggested checks lists likely local commands for this PR.

  • Hold conditions names situations that should stop merge until resolved or explicitly waived.

  • GitHub comment summary shows bilingual risk, reason, and review focus, with details folded by default.

The plan is advisory. When the PR body, maintainer judgment, or scientific impact suggests higher risk than the file map, use the higher risk level.

Examples#

Hamiltonian changes should be treated as high risk:

printf "dptb/nn/hamiltonian.py\n" | python scripts/ci/pr_review_plan.py --stdin

Docs-only changes should normally stay low risk:

printf "docs/index.rst\n" | python scripts/ci/pr_review_plan.py --stdin

GitHub comment preview:

printf "dptb/utils/argcheck.py\n" | python scripts/ci/pr_review_plan.py --stdin --format github-comment