bitflicker64 commented on code in PR #3197:
URL: https://github.com/apache/hugegraph/pull/3197#discussion_r3997764992
##########
.github/PULL_REQUEST_TEMPLATE.md:
##########
@@ -65,3 +65,5 @@ For example:
- [ ] `Doc - TODO` <!-- Your PR changes impact docs and you will update later
-->
- [ ] `Doc - Done` <!-- Related docs have been already added or updated -->
- [ ] `Doc - No Need` <!-- Your PR changes don't impact/need docs -->
+
+Related hugegraph-doc PR or issue: <!-- required for Doc - TODO and Doc - Done
-->
Review Comment:
⚠️ Two things work against this field being filled in.
1. Line 63, directly above, still says `DO NOT REMOVE THIS SECTION. CHECK
THE PROPER BOX ONLY.` A contributor following that ticks a box and leaves this
line empty.
2. `Doc - Done` is defined as "Related docs have been already added or
updated", which also covers in-repo docs (`README.md`, module READMEs, `docs/`,
`AGENTS.md`). This PR is itself an example. For those, a hugegraph-doc link
does not exist, yet the hint marks it required.
The hint is also an HTML comment, so it disappears once the PR is rendered,
and reviewers never see that the field was meant to be required.
Suggested change: reword line 63 to cover the field too, for example `CHECK
THE PROPER BOX AND FILL IN THE LINK BELOW`, and scope the hint to `required for
Doc - TODO; for Doc - Done, when the docs live in hugegraph-doc`.
##########
AGENTS.md:
##########
@@ -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
Review Comment:
🧹 `wrap at 120` does not describe the current `README.md`. At this head, 47
of its 390 lines are longer than 120 columns. That count covers the badge rows,
the module table (L114-116) and the ASCII architecture diagram, none of which
can wrap, and also plain prose (L25-27, L34, L175, L204-208). Given as an agent
instruction, this invites reflowing the whole README in unrelated PRs, which
cuts against the `Keep the change minimal` rule added above. It is also a
formatting rule rather than a cross-module dependency, so it fits `Style &
Pre-commit` better than this list.
Suggested change: limit it to new or edited prose (`wrap new prose at 120;
tables, links and diagrams are exempt`) and move it under `Style & Pre-commit`.
##########
AGENTS.md:
##########
@@ -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`.
Review Comment:
🧹 The rule here and the rule in `docs/CONTRIBUTING.md` are not the same as
the one in the template. This line and the CONTRIBUTING paragraph both say the
paired hugegraph-doc **PR** lands together with the code.
`.github/PULL_REQUEST_TEMPLATE.md` then accepts `hugegraph-doc PR or issue` and
keeps `Doc - TODO` ("you will update later"), so an issue link plus deferred
docs passes the template. An agent reading this file will hold contributors to
a stricter rule than the one they are shown.
Suggested change: choose one rule and write it the same way in all three
files. Either allow a tracking issue here and in CONTRIBUTING, or drop `or
issue` from the template field.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
