Skip to content

doc: state the design philosophy and the doc-sync rule for contributors - #3197

Draft
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc/agents-design-philosophy
Draft

doc: state the design philosophy and the doc-sync rule for contributors#3197
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc/agents-design-philosophy

Conversation

@bitflicker64

@bitflicker64 bitflicker64 commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Purpose of the PR

Draft for discussion.

AGENTS.md describes the module layout, the build and the test profiles, but it says
nothing 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 Status section, so the intent is there, but the first option is:

- [ ] `Doc - TODO`  <!-- Your PR changes impact docs and you will update later -->

"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.md does 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:

  • new Design philosophy section: extend existing code before introducing a new
    abstraction, keep the change minimal, one concern per PR, link the issue when something
    needs real context instead of writing a long inline comment
  • two entries under Cross-module notes, in the same "change X, also update Y" shape as
    the 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, so
    this 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, a
    configuration item or a Dockerfile opens the matching hugegraph-doc PR at the same
    time, and that the two merge together.

24 lines added, nothing removed or reworded.

Two open points for review:

  1. Should Doc - TODO stay at all, or should the choice be Done or No Need? A field
    that 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.
  2. .github/PULL_REQUEST_TEMPLATE.md is byte identical in hugegraph-toolchain and
    hugegraph-computer. If this lands, both want the same line.
  3. CONTRIBUTING.md says the website copy at
    https://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

  • Trivial rework / code cleanup without any test coverage. (No Need)
  • Already covered by existing tests, such as (please modify tests here).
  • Need tests and can be verified as follows:
    • xxx

Does this PR potentially affect the following parts?

Documentation Status

  • Doc - TODO
  • Doc - Done
  • Doc - No Need

@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 37.77%. Comparing base (e85b36a) to head (96a48ad).

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.
📢 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
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.

1 participant