Skip to content

docs(contributing): cite the issue, not the pull request, on the conventions pages (#719) - #978

Merged
JarryShaw merged 1 commit into
mainfrom
docs/719-cite-issues-not-pull-requests
Oct 1, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/719-cite-issues-not-pull-requests

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Oct 1, 2026 •

Copy link
Copy Markdown
Owner

Please follow the guide below

What is the purpose of your pull request?

  • fix — corrects a defect
  • feat — adds a feature
  • perf — changes performance, not behaviour
  • refactor — changes neither behaviour nor performance
  • test — tests only
  • docs — documentation only
  • ci — workflows or build tooling
  • chore — anything else

Description of your pull request and other information

Implements the #719 ruling under docs/source/: a pull request describes a point in time, so cite
the issue the work belonged to, or describe the change with no number at all.

Counts, derived against this base. 582 #NNN references under docs/source/ — 220 pull
requests, 358 issues, and 4 occurrences naming a GitHub discussion (#106, #251), which is neither.
188 of the 220 sit in changelog/ and 1 more in changelog.rst, both exempt, leaving 31 acted
on
: process.rst 22, registry-protocol.rst 5, extension-header-subclassing.rst 2,
mint-criterion.rst 2. That bucket is now at zero pull-request references; its issue references rose
72 → 87.

Changed. process.rst — breaking's worked examples now cite #805, #759, #618, #806 and #778;
the label census and the shared-changelog mentions are described rather than numbered, and the
commit-count command looks its pull request up by title. registry-protocol.rst — #903, #808, #877;
the two mh.py overrides' widening and their later deletion were each ruled in a review thread
rather than on an issue, so both read as prose. extension-header-subclassing.rst — #917, the rename
the second-base ruling was given in review of, since no issue owns that ruling alone.
mint-criterion.rst — #841 ×2.

Verified. 37 passed, 1 pre-existing skip. Sphinx against a main baseline: 63 warning lines
each, 0 new, 0 gone, 7 duplicate-label and 0 orphan both sides, each build's pcapkit.__file__
printed to prove its tree. All 45 link targets are issues and every displayed #NNN matches its own
URL. Over-88 lines under docs/source/contributing/ went 23 → 22, none added.

@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 1, 2026
…entions pages (#719)

* `extension-header-subclassing.rst`: the second-base ruling now cites the rename
  issue it was given in review of, twice. No issue owns that ruling on its own.
* `mint-criterion.rst`: the mint criterion and the company-name reasoning now cite
  the `Socket._missing_` fix's own issue rather than its pull request.
* `registry-protocol.rst`: three citations re-pointed at the issue behind the change
  — the case-sensitivity audit, the `extend_enum` removal and the `EnumLookup`
  re-parenting. The two `mh.py` overrides' widening and their later deletion were
  each ruled in a review thread rather than on an issue, so both read as prose: the
  widening issue carries only the widening ruling, and citing it for the deletion
  pointed at the wrong thread.
* `process.rst`: the `breaking` worked examples and the label census now cite issues
  or describe the change; the shared changelog is described rather than numbered, and
  its commit-count command looks the pull request up by title instead of hard-coding
  a number.

Out of scope by the owner's rulings, not by my own caution: the changelog is exempt,
so neither `docs/source/changelog/` (188 references) nor the top-level
`docs/source/changelog.rst` summary (1) is touched — the latter repeats `0.14.3`'s
`(#29, #30)` verbatim from the directory, so editing one would desynchronise the pair.
`tests/**` is exempt too, and still cites pull requests in its own docstrings.

Verified: `tests/project/test_conventions_doc_claims.py` 37 passed, 1 pre-existing
skip; a full Sphinx build's warning set is byte-identical to the `main` baseline, 63
lines each, 0 new and 0 gone, 7 duplicate-label and 0 orphan both sides; every
displayed `#NNN` matches its own URL and all 45 link targets are issues; over-88 lines
under `docs/source/contributing/` went 23 to 22, with none added.
@JarryShaw
JarryShaw force-pushed the docs/719-cite-issues-not-pull-requests branch from b4823c4 to df61fce Compare October 1, 2026 21:03
@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Oct 1, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO at df61fce5e — sonnet cross-review, round 2. Labelled review: good-to-go.

The deletion sentence is now true and its referent resolves locally. Issue #935's thread holds
only the widening ruling; the deletion was decided in #940's own review thread, where the question
("why must we have the two overrides tho?") and the answer both sit. So "given in review of the
widening itself" is literally accurate. And "the widening itself" nominalizes "widened" nine words
earlier in the same table cell — a local antecedent, where the old "that same widening" had no
widen-rooted word anywhere in that cell.

It caught a trap in my own brief, and it would have cost a false accusation. I told it to read
git diff b4823c4d1 df61fce5e. That diff is contaminated — the branch was rebased between rounds onto
a main that had merged a sibling change, so it reads:

naive b4823c4d1..df61fce5e        4 files, +312/-8   <- includes a 297-line page this author never wrote
against the real parent           4 files,  +76/-60  <- the actual change
tests/project/... vs real parent  empty              <- 100% rebase drift

I already knew the main-moved-under-a-branch form of this; the rebase-between-review-rounds form is
new to me.
Even an explicit old-head-to-new-head pair mixes in everything the new base absorbed.
Compare against the PR's actual parent, or restrict to paths the intervening merge did not touch — which
is what it did, two ways, before concluding.

Re-derived independently: all 28 distinct #NNN across the four files classify as issues, zero
pull requests, zero discussion-candidates; link count 45 under the test's own _every_page() scope
with 0 pull-targeted and 0 displayed-versus-URL mismatches, and it explained the gap against its first
narrower count of 43 rather than leaving it hanging; over-88 lines 23 → 22 measured against current
main, with one line genuinely dropped and one merely shifted, so "none added" holds;
37 passed, 1 skipped, 140 subtests. Orphan sweep over all four files: 8 hits, every one read in
context, no orphans.

Both the commit message and the PR body were corrected to match the narrowed diff — three citations
re-pointed rather than five, with the two pull-request-sourced ones carved out as prose.

UNVERIFIED by it: the Sphinx warning-set rebuild, skipped within budget.

Unpublished and awaiting you — I do not merge.

@JarryShaw
JarryShaw merged commit 5503e30 into main Oct 1, 2026
63 checks passed
@JarryShaw
JarryShaw deleted the docs/719-cite-issues-not-pull-requests branch October 1, 2026 21:32
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 1, 2026
@JarryShaw JarryShaw added this to the 1.5 milestone Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant