Skip to content

doc: simplify all AGENTS.md & update memories - #3197

Merged
imbajin merged 2 commits into
apache:masterfrom
bitflicker64:doc/agents-design-philosophy
Sep 17, 2026
Merged

imbajin merged 2 commits into
apache:masterfrom
bitflicker64:doc/agents-design-philosophy

Conversation

@bitflicker64

@bitflicker64 bitflicker64 commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Visual summary

Documentation sync

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

  • Reduce all six AGENTS.md files to fewer than 100 lines while keeping component relationships,
    common commands and repository-specific pitfalls inline. Link detailed POM, CI and deployment references.
  • Require user-visible feature, configuration and deployment changes to ship with matching documentation.
    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.
  • Correct stale Serena notes for deployment topology, distribution output, compiler targets and test scope.
  • Update README navigation without imposing a repository-wide prose reflow.

Validation

  • Independent read-only review of the final diff: no remaining substantive findings.
  • All six AGENTS.md files are under 100 lines; their local links resolve.
  • git diff --check passed.
  • Documentation-only change; no runtime tests executed.

Documentation Status

  • Doc - TODO: synchronize the website contribution guidelines before merging.
  • Doc - Done
  • Doc - No Need

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.

@bitflicker64
bitflicker64 force-pushed the doc/agents-design-philosophy branch from b9aa16c to bac0ac3 Compare September 9, 2026 06:22
@bitflicker64 bitflicker64 changed the title doc: add design philosophy and doc-sync notes to AGENTS.md doc: state the design philosophy and the doc-sync rule for contributors Sep 9, 2026
@codecov

codecov Bot commented Sep 9, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 41.13%. Comparing base (e85b36a) to head (899f072).
⚠️ Report is 8 commits behind head on master.

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@bitflicker64
bitflicker64 force-pushed the doc/agents-design-philosophy branch from bac0ac3 to 4134bbe Compare September 9, 2026 07:59
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.
@bitflicker64
bitflicker64 force-pushed the doc/agents-design-philosophy branch from 4134bbe to 96a48ad Compare September 9, 2026 08:02
@bitflicker64
bitflicker64 marked this pull request as ready for review September 12, 2026 13:42

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

Comment thread .github/PULL_REQUEST_TEMPLATE.md Outdated
Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
- 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
@imbajin imbajin changed the title doc: state the design philosophy and the doc-sync rule for contributors doc: simplify all AGENTS.md & update memories Sep 17, 2026
@imbajin
imbajin merged commit 924d9f3 into apache:master Sep 17, 2026
24 checks passed
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