doc: simplify all AGENTS.md & update memories - #3197
Conversation
b9aa16c to
bac0ac3
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3197 +/- ##
============================================
+ Coverage 37.79% 41.13% +3.34%
- Complexity 6563 7212 +649
============================================
Files 800 802 +2
Lines 68960 69393 +433
Branches 9166 9237 +71
============================================
+ Hits 26061 28546 +2485
+ Misses 39834 37585 -2249
- Partials 3065 3262 +197 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
bac0ac3 to
4134bbe
Compare
AGENTS.md covered structure, build and test workflow, but said nothing about how code is expected to be written here, so agents fell back on generic best practice and reached for new abstractions. The PR template already asks for a documentation status, but "Doc - TODO" means "you will update later" with nothing attached to it, so the follow-up often does not happen and the docs drift away from the code. CONTRIBUTING did not mention documentation at all in the section on opening a PR. Adds a short design philosophy section to AGENTS.md, one visible field under the existing Documentation Status options for the hugegraph-doc PR link, and the paired doc PR expectation in CONTRIBUTING where a contributor reads it before opening the PR. The three options keep their current wording so the block stays identical to the one in hugegraph-toolchain and hugegraph-computer.
4134bbe to
96a48ad
Compare
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: no. Summary: The design-philosophy section and the doc-sync paragraph are additive and read well, but the three edited files disagree about what the rule actually is, and the README guidance does not match the README it describes. Separately, open point 2 in the description says the PR template is byte identical in hugegraph-toolchain and hugegraph-computer; it is not (the Documentation Status block is identical, the rest of the file differs in several places), so that follow-up is a hand merge rather than a copy. Evidence: git show 96a48ad:.github/PULL_REQUEST_TEMPLATE.md, AGENTS.md, docs/CONTRIBUTING.md and README.md at head; awk 'length>120' README.md returns 47 lines, including prose; diff of .github/PULL_REQUEST_TEMPLATE.md fetched via gh api from apache/hugegraph, apache/hugegraph-toolchain and apache/hugegraph-computer default branches.
- keep module guidance concise with on-demand references - align documentation requirements across contributor entry points - correct stale Serena notes against current source - clarify README navigation and generated source paths
Visual summary
Purpose of the PR
Agent guidance repeated generic instructions and stale repository details across six files.
Documentation requirements also disagreed between AGENTS.md, the PR template and the contribution guide.
Main changes
common commands and repository-specific pitfalls inline. Link detailed POM, CI and deployment references.
In-repository docs belong in the same PR; website changes use a paired hugegraph-doc PR.
Doc - TODO means pending before merge, and a follow-up issue alone does not satisfy the requirement.
Validation
Documentation Status
Documentation in this PR: AGENTS.md, module AGENTS.md files, docs/CONTRIBUTING.md,
README.md, the PR template and Serena notes.
Paired hugegraph-doc PR: pending.
Related repositories may adopt the policy separately; their full PR templates are not byte-identical.