doc: state the design philosophy and the doc-sync rule for contributors - #3197
Draft
bitflicker64 wants to merge 1 commit into
Draft
doc: state the design philosophy and the doc-sync rule for contributors#3197bitflicker64 wants to merge 1 commit into
bitflicker64 wants to merge 1 commit into
Conversation
11 tasks
bitflicker64
force-pushed
the
doc/agents-design-philosophy
branch
from
September 9, 2026 06:22
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% 37.77% -0.02%
+ Complexity 6563 6560 -3
============================================
Files 800 800
Lines 68960 68960
Branches 9166 9166
============================================
- Hits 26061 26052 -9
- Misses 39834 39841 +7
- Partials 3065 3067 +2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
bitflicker64
force-pushed
the
doc/agents-design-philosophy
branch
from
September 9, 2026 07:59
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.
bitflicker64
force-pushed
the
doc/agents-design-philosophy
branch
from
September 9, 2026 08:02
4134bbe to
96a48ad
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose of the PR
Draft for discussion.
AGENTS.mddescribes the module layout, the build and the test profiles, but it saysnothing about how code is expected to be written in this repo. Without that, agents fall
back on generic best practice: they add an interface where the existing class would do,
widen a fix into a refactor, or explain a tricky case in a long block comment that then
drifts out of date.
The same gap exists on the documentation side, in a different form. The PR template already
has a
Documentation Statussection, so the intent is there, but the first option is:"You will update later" is a promise with nothing attached to it. No link, no issue, no
follow-up, so once the code PR merges the box is the only record that documentation was
owed, and it stops being visible to anyone. The result is documentation that describes an
older version of the code, which readers and search tools then pick up as current.
CONTRIBUTING.mddoes not mention documentation at all in the section on opening a PR,which is the point where a contributor decides whether to write any.
Main Changes
AGENTS.md, kept short on purpose so the file stays usable as a prompt:Design philosophysection: extend existing code before introducing a newabstraction, keep the change minimal, one concern per PR, link the issue when something
needs real context instead of writing a long inline comment
Cross-module notes, in the same "change X, also update Y" shape asthe existing ones: the paired hugegraph-doc PR, and the README staying thin at 120
columns
For contributors, who do not read
AGENTS.md:.github/PULL_REQUEST_TEMPLATE.md: one visible field under the existing options,Related hugegraph-doc PR or issue:. The three options keep their current wording, sothis block stays identical to the one in hugegraph-toolchain and hugegraph-computer and
the change is purely additive. The field sits in the rendered body rather than in an
HTML comment, which GitHub strips, and it applies to whichever option is ticked instead
of repeating the prompt on each one. This follows the shape kubernetes uses for its
documentation and release-note fields: visible heading, guidance in the comment, an
obviously empty field below.
docs/CONTRIBUTING.md: one paragraph in section 4, saying that a change to a feature, aconfiguration item or a
Dockerfileopens the matching hugegraph-doc PR at the sametime, and that the two merge together.
24 lines added, nothing removed or reworded.
Two open points for review:
Doc - TODOstay at all, or should the choice beDoneorNo Need? A fieldthat asks for the link is the softer option and is what this PR does. Nothing yet
checks that the field is filled in; a small workflow on the paths that touch features,
configs and Dockerfiles could do that, if that is wanted.
.github/PULL_REQUEST_TEMPLATE.mdis byte identical in hugegraph-toolchain andhugegraph-computer. If this lands, both want the same line.
CONTRIBUTING.mdsays the website copy athttps://hugegraph.apache.org/docs/contribution-guidelines/ is authoritative. If this
lands, the same paragraph needs a matching hugegraph-doc PR, which is the rule applying
to itself.
Verifying these changes
Does this PR potentially affect the following parts?
Documentation Status
Doc - TODODoc - DoneDoc - No Need