doc: require a paired hugegraph-doc PR for feature and config changes - #3198
Closed
bitflicker64 wants to merge 1 commit into
Closed
doc: require a paired hugegraph-doc PR for feature and config changes#3198bitflicker64 wants to merge 1 commit into
bitflicker64 wants to merge 1 commit into
Conversation
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.
Contributor
Author
|
Folded into #3197, which now carries the AGENTS.md, PR template and CONTRIBUTING changes as one change. Nothing here is lost. |
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
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, companion to #3197.
The PR template already has a
Documentation Statussection, so the intent is there. Theproblem is the first option:
"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
.github/PULL_REQUEST_TEMPLATE.md:Doc - TODOnow asks for a link, either thehugegraph-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, aconfiguration item or a
Dockerfileopens the matching hugegraph-doc PR at the sametime, and that the two merge together.
7 lines added, 1 reworded.
Two open points for review:
Doc - TODOrequire a link, or be removed entirely so the choice isDoneorNo Need? Requiring a link is the softer option and is what this PR does.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