Skip to content

docs(governance): stop recommending forward declarations over header includes - #8339

Open
Critsium-xy wants to merge 1 commit into
deepmodeling:developfrom
Critsium-xy:docs/remove-forward-declaration-guidance
Open

Critsium-xy wants to merge 1 commit into
deepmodeling:developfrom
Critsium-xy:docs/remove-forward-declaration-guidance

Conversation

@Critsium-xy

Copy link
Copy Markdown
Collaborator

Reminder

  • I have read AGENTS.md and docs/developers_guide/agent_governance.md.
  • I have linked an issue or explained why this PR does not need one.
  • I have added adequate unit tests and/or case tests, or explained why not.
  • I have listed the exact verification commands run and their results.
  • I have described user-visible behavior changes, including INPUT parameter changes.
  • I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other source/ changes.
  • I have requested any needed governance exception below.

Linked Issue

No separate issue: this is a governance documentation and checker message refinement requested during recent PR reviews (e.g. #8136, #8328).

Unit Tests and/or Case Tests for my changes

  • Commands run:
    • Verified LF line endings (hasCR=False) on all 5 modified files and ran git diff --check (passed with no issues).
    • Updated tools/03_code_analysis/test_agent_governance_check.py::AgentGovernanceCheckTest::test_warns_for_new_header_include to assert that the Header dependency review warning no longer suggests forward declarations.
  • Result summary:
    • Formatting, LF line-ending, and diff checks passed locally.
  • Checks not run, with reason:
    • python3 -m unittest tools/03_code_analysis/test_agent_governance_check.py was not run locally because this Windows environment does not have a local Python 3 interpreter configured; CI (Agent Governance) will run the test suite on this PR.

What's changed?

  • Keep the existing Header dependency review warning in tools/03_code_analysis/agent_governance_check.py, but update its suggested action text so it no longer instructs contributors or AI agents to replace explicit #include directives with forward declarations.
  • Update AGENTS.md, docs/developers_guide/agent_governance.md, and .github/instructions/abacus-governance.instructions.md to remove guidance that encourages replacing explicit #include dependencies with forward declarations (which makes header dependencies implicit and harder to trace).
  • Add an assertion in tools/03_code_analysis/test_agent_governance_check.py verifying the updated warning wording.

Governance Notes

  • INPUT/docs changes: Updates governance documentation (AGENTS.md, docs/developers_guide/agent_governance.md, .github/instructions/abacus-governance.instructions.md) and checker message text; no INPUT parameter or user-facing calculation behavior is changed.
  • Core module impact: None (source/ is untouched).
  • Exceptions requested: None.

@ABACUS-PR-BOT ABACUS-PR-BOT left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No implementation defect found in this wording change.

Static review of 12d4827665fd2a1d6d1bd4b77e9b8d0073ae3372: git diff --check passed; the checker and unit suite were not executed, and CI run results were not inspected.

result = self.run_checker("--base", self.base, "--head", head)

self.assert_warns_with_success(result, "Header dependency review")
self.assertNotIn("forward declaration", result.stdout.lower())

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: The PR verification note relies on Agent Governance to run this test suite, but that workflow only invokes agent_governance_check.py. Please record a run of python3 -m unittest tools/03_code_analysis/test_agent_governance_check.py or add an explicit CI test step, and update the note.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants