Skip to content

doc: require a paired hugegraph-doc PR for feature and config changes - #3198

Closed
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc/require-paired-doc-pr
Closed

doc: require a paired hugegraph-doc PR for feature and config changes#3198
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc/require-paired-doc-pr

Conversation

@bitflicker64

Copy link
Copy Markdown
Contributor

Purpose of the PR

Draft for discussion, companion to #3197.

The PR template already has a Documentation Status section, so the intent is there. The
problem is the first option:

- [ ] `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

  • .github/PULL_REQUEST_TEMPLATE.md: Doc - TODO now asks for a link, either the
    hugegraph-doc PR or a tracking issue. Same three options, same structure, one comment
    reworded.
  • 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.

7 lines added, 1 reworded.

Two open points for review:

  1. Should Doc - TODO require a link, or be removed entirely so the choice is Done or
    No Need? Requiring a link is the softer option and is what this PR does.
  2. 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

The PR template already asks for a documentation status, but "Doc - TODO"
means "you will update later" and nothing tracks it, so the follow-up
often does not happen and the docs drift away from the code.

Ask for a link next to Doc - TODO, either the hugegraph-doc PR or a
tracking issue, and state the expectation in CONTRIBUTING where a
contributor reads it before opening the PR.
@bitflicker64

Copy link
Copy Markdown
Contributor Author

Folded into #3197, which now carries the AGENTS.md, PR template and CONTRIBUTING changes as one change. Nothing here is lost.

@bitflicker64
bitflicker64 deleted the doc/require-paired-doc-pr branch September 9, 2026 06:23
@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.79%. Comparing base (e85b36a) to head (74c31fb).

Additional details and impacted files
@@            Coverage Diff            @@
##             master    #3198   +/-   ##
=========================================
  Coverage     37.79%   37.79%           
- Complexity     6563     6566    +3     
=========================================
  Files           800      800           
  Lines         68960    68960           
  Branches       9166     9166           
=========================================
+ Hits          26061    26066    +5     
+ Misses        39834    39829    -5     
  Partials       3065     3065           

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

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