From 96a48ad677d2af09e9a01eacf8251af102dd5efc Mon Sep 17 00:00:00 2001 From: Himanshu Verma Date: Wed, 9 Sep 2026 13:32:12 +0530 Subject: [PATCH] doc: state the design philosophy and the doc-sync rule for contributors 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. --- .github/PULL_REQUEST_TEMPLATE.md | 2 ++ AGENTS.md | 16 ++++++++++++++++ docs/CONTRIBUTING.md | 6 ++++++ 3 files changed, 24 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 2a8a408a98..7d63f9c3ca 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -65,3 +65,5 @@ For example: - [ ] `Doc - TODO` - [ ] `Doc - Done` - [ ] `Doc - No Need` + +Related hugegraph-doc PR or issue: diff --git a/AGENTS.md b/AGENTS.md index 07daf17662..9edb9ae778 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,6 +83,18 @@ mvn test -pl hugegraph-store/hg-store-test -am Before writing new tests, check existing suites under `hugegraph-server/hugegraph-test/`. +## Design philosophy + +Match the codebase, do not improve on it. + +- Extend existing code before introducing a new abstraction. A new interface, factory + or base class needs a reason beyond symmetry. +- Keep the change minimal: the smallest edit that fully solves the issue. Adjacent + cleanups belong in their own PR. +- One concern per PR. Do not bundle an unrelated fix because you were already in the file. +- Comments stay short. When something needs real context to explain, link the GitHub + issue instead of writing a paragraph in the source. + ## Style & Pre-commit - Line 120, 4-space indent, LF, UTF-8, **no star imports** @@ -101,6 +113,10 @@ Before writing new tests, check existing suites under `hugegraph-server/hugegrap and `install-dist/scripts/dependency/known-dependencies.txt`. - `hugegraph-commons` is shared by every module; `hugegraph-struct` must precede PD/Store; server backends depend on `hugegraph-core`. +- Feature, config and `Dockerfile` changes ship a paired PR in `apache/hugegraph-doc`. + Land both together; docs that trail the code go stale without anyone noticing. +- README: wrap at 120, keep it thin, push detail to hugegraph-doc, and fold the + non-urgent parts into `
`. ## Additional context files diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7056afd978..8d63e0608c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -125,6 +125,12 @@ Note that since GitHub requires submitting code through `username + token` (inst Go to the web page of GitHub fork repo, there would be a chance to create a Pull Request after pushing to a new branch, click the button "Compare & pull request" to do it. Then edit the description for proposed changes, which can just be copied from the commit message. +If the change touches a feature, a configuration item or a `Dockerfile`, open the matching +documentation PR in [hugegraph-doc](https://github.com/apache/hugegraph-doc) at the same time +and link the two together. Both should merge together. Documentation that trails the code +goes stale quietly, and the gap is only found when a user or a search tool reads the wrong +thing. + Note: please make sure the email address you used to submit the code is bound to the GitHub account. For how to bind the email address, please refer to https://github.com/settings/emails: image