Skip to content

docs(github): review the non-workflow metadata under .github/ - #637

Merged
JarryShaw merged 1 commit into
mainfrom
chore/github-metadata-cleanup
Sep 22, 2026
Merged

docs(github): review the non-workflow metadata under .github/#637
JarryShaw merged 1 commit into
mainfrom
chore/github-metadata-cleanup

Conversation

@JarryShaw

@JarryShaw JarryShaw commented Sep 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Requested by the owner, in their words: "let's have an agent to revise/cleanup the docs under .github path as well, like the release.yml (seems no longer needed per create-release GHA's update to read from changelog.md?) and issue templates and pr templates". No issue tracks this.

.github/workflows/** is untouched — #626 owns lint.yml, and create-release.yml/cron-vendor.yml are the path about to be exercised for 1.5.0b5. They were read, not edited.

release.yml is live — the hypothesis is the wrong way round

Do not delete it. create-release.yml does not replace the generated notes with CHANGELOG.md; it prepends to them, and on the release about to be cut it contributes nothing at all.

Read on this branch's base:

Line What it does
create-release.yml:121-147 the Select release body step, which decides whether CHANGELOG.md is used
create-release.yml:129-132 CHANGELOG.md absent → exits without setting path, so generated notes alone
create-release.yml:137-140 heading token ≠ released version → generated notes alone, logging "Expected for a pre-release and for a .postN vendor refresh, neither of which has a changelog entry of its own"
create-release.yml:158-162 comment: the action "fetches the generated notes itself and joins them as <body>\n\n<generated>, so the hand-written entry leads and the pull-request list follows"
create-release.yml:164 generate_release_notes: true — unconditional, on both paths

1.5.0b5 is a pre-release, so CHANGELOG.md's heading (1.5.0) will not match and the release body comes entirely from the categories in this file. Deleting it would have degraded the notes on exactly that release.

What release.yml actually needed

Two things, both measured.

The catch-all was mislabelled. Categorisation keys on pull-request labels and nothing else — GitHub's documentation has no title or conventional-commit matching, so the type(scope): prefix this project uses cannot reach this file. And in practice nothing but Dependabot labels anything: all 20 most recently merged PRs carry zero labels, and only 8 of the last 40 issues carry any, none above #576. So every hand-authored PR falls through to labels: ['*'] — which was titled 🏕 Features. Across the last 40 merged PRs:

type count
fix 24
test 6
docs 6
feat 2
perf 1

A "Features" heading described 2 of 39 human PRs. It is now 🏕 Changes.

The catch-all was first, not last. GitHub documents * as catching pull requests that "didn't match any of the previous categories" — so a * category placed first matches everything, and 👒 Dependencies was receiving PRs only because the Features entry carried exclude: labels: [dependencies]. Ordering dependencies ahead of the catch-all makes the exclude unnecessary, so it is gone.

To be precise about provenance, since an earlier draft of this description overstated it: GitHub's own documentation example for a repository like this one uses the opposite form — catch-all first, with exclude: dependencies — so the previous file was not wrong, and this is not "the documented idiom". Both orderings produce an identical partition: no PR lands in two categories and none is dropped. The reorder is kept because one fewer moving part is better, not because the old one misbehaved. The substantive fix here is the retitling above, which is independent of the ordering.

Both title and labels are documented as Required and both are still present on both categories.

ISSUE_TEMPLATE/config.yml — new, and this was a real gap

SECURITY.md:25-30 says "Please do not open a public issue for a security problem" and points at https://github.com/JarryShaw/PyPCAPKit/security/advisories/new. The "New issue" chooser offered no route there — the only visible option was the public bug template, so the repository was inviting a vulnerability to be filed publicly.

The new file adds that link plus Discussions (enabled on this repo) and the docs site. blank_issues_enabled: true is explicit and deliberate: the maintainer files most issues without a template and turning it off would remove that route.

The templates, judged against how issues and PRs are really written

An important correction to the framing, because it changes the answer. The recent corpus is not external bug reports: of 175 issues, 134 are by the maintainer, and all 40 filed in the last ~45 hours are maintainer-filed via agents. Likewise 0 of the 20 most recent merged PRs use the PR template — every one is maintainer-authored with a bespoke body. External reporters did use the template headings, up to #240/#289.

So "recent issues ignore the template" is not evidence the template fails its audience; its audience is the external newcomer, who has largely stopped filing at all. Rewriting these templates to imitate agent-authored prose would optimise them for the people who bypass them. I did not do that. Also relevant: #613 reviewed all three templates two days ago — it de-staled bug_report.md's Python versions, added the pcapkit version field, added the PR checklist's test-run and changelog rows, and found feature_request.md needed nothing. That work is not redone or reversed here.

What is left is audience-independent:

bug_report.md

  • Adds a Reproduction section. The template had none — no reproduction ask of any kind, which is the one field every bug template has. This is the substantive gap.
  • Asks for the commit when the reporter is working from a checkout, not just __version__. An editable install can resolve well behind the branch; SeekableReader.truncate pads on the wrong side and returns fewer octets than requested #622 hit exactly that and said so.
  • Marks the traceback optional. PCAPKIT_DEVMODE=true is still valid (pcapkit/utilities/logging.py:64) and docs: repair the Code of Conduct's rendering and refresh CONTRIBUTING #613 checked it, so it stays — but the section assumed the bug crashes, and the current defect corpus is silent wrongness with nothing to paste. 0 of the last 40 issues mention PCAPKIT_DEVMODE.
  • Drops the pinned 1.5.0b4 example, which goes stale the moment 1.5.0b5 ships, keeping the command that never does.
  • Points Additional context at file:line and at why existing tests miss it, instead of leaving an unnamed bucket — 3 of 175 issues left its placeholder text (Add any other context about the problem here.) in place verbatim, and 17 did the same with the System information block's (A clear and concise description of your system information.).

PULL_REQUEST_TEMPLATE.md

  • The three purpose boxes (Bug fix / Improvement / New feature) had no box for a docs or test change — 12 of the last 39 human PRs. They are now the eight types CONTRIBUTING.md:133 documents (feat, fix, docs, test, perf, refactor, ci, chore).
  • The /search?q= link used GitHub's retired per-repo endpoint. It still works by redirect (302 → github.com/search?q=repo%3A…), so this is tidying, not repair.

feature_request.md — #613 found it needed nothing and that still holds. The only change is the label below; the body is byte-identical.

Both issue templates now self-label (labels: bug, labels: enhancement). Only 32 label applications exist across 175 issues and nothing after #576 carries one; the template is the cheapest place to fix that.

Every reference verified

Reference Verdict
CONTRIBUTING.md#coding-style RESOLVES — ## Coding style, CONTRIBUTING.md:89
CONTRIBUTING.md#changelog-entries RESOLVES — ## Changelog entries, CONTRIBUTING.md:60
CONTRIBUTING.md#format-of-the-commit-message (new) RESOLVES — ### Format of the Commit Message, CONTRIBUTING.md:107
make pylint / mypy / isort / test ALL RESOLVE — Makefile:134, :137, :124, :79
docs/source/changelog/ RESOLVES
PCAPKIT_DEVMODE RESOLVES — read at pcapkit/utilities/logging.py:64, true is an accepted value
pcapkit.__version__ RESOLVES — pcapkit/__init__.py:132, 1.5.0b4
/pulls?q=is%3Apr (new) RESOLVES — 200
/security/advisories/new (new) RESOLVES — 302 to login, not 404, so private reporting is enabled
/discussions (new) RESOLVES — 200, Discussions enabled
jarryshaw.github.io/PyPCAPKit/ (new) RESOLVES — 200
README.rst anywhere under .github/ not referenced — nothing to fix from #619

No stale path was found in any template. The README rename did not leave a dangling reference here.

FUNDING.yml — cleaned, values untouched

Nine of its twelve lines were GitHub's commented-out roster of every other platform, carrying "Replace with a single X username" instructions aimed at whoever adopted the file. Those are adopter instructions rather than configuration — the same reasoning #624 used to remove Contributor Covenant 3.0's [NOTE placeholder — and one of them, otechie, is no longer a platform GitHub documents. They are gone; the three live values are unchanged.

Two findings I did not act on, because removing a funding route is the owner's call:

  • patreon: jarryshaw → patreon.com/jarryshaw redirects to patreon.com/profile/creators?u=100037, a generic landing page rather than a creator page. Suggestive that the button leads nowhere useful, but Patreon redirects unauthenticated requests aggressively, so not conclusive.
  • tidelift: pypi/pypcapkit → redirects to sonarsource.com/solutions/security/?tidelift=tidelift-redirect. Tidelift was acquired by Sonar, so this funding button now lands on a vendor marketing page.

dependabot.yml — unchanged, deliberately

Valid, and it parses. Two gaps exist and I recommend leaving both, on the evidence: of the last 15 Dependabot PRs, 14 were closed unmerged and the last activity was September 2024. Widening its scope would manufacture PRs the owner demonstrably rejects.

Verification

release.yml, FUNDING.yml, dependabot.yml and the new config.yml all parse under PyYAML, and release.yml is asserted against GitHub's documented changelog schema — title and labels present on every category, no key outside {title, labels, exclude}, catch-all last and unique. Both templates' front matter parses and uses only documented keys.

python util/changelog_md.py --check exits 0.

No changelog entry. Nothing here changes the library, its API or its behaviour — it is repository metadata seen by contributors and by the release-notes generator. This follows #613, the closest precedent, which edited these same files and recorded "No changelog entry — this is contributor-facing documentation, not user-visible"; #626 does the same for CI tooling, though it is still open and so carries less weight as precedent. Flagging it because #624 went the other way, so the convention is genuinely unsettled and this is a judgement call rather than a rule.

No tests were run: nothing here touches pcapkit/.

Recommended, not done

  • Issue forms (.yml) instead of legacy Markdown. Forms give required fields and structured output, and would mechanically enforce the reproduction and version fields this PR merely asks for. I am not converting: it changes how every future reporter interacts with the repo, it cannot be partially adopted per-field, and on the evidence above the external-reporter population is small enough that the owner should weigh whether the friction is worth it. Your call.
  • Enable Dependabot for github-actions, only if action-pin updates are wanted — see the closure record above.
  • Decide on the Patreon and Tidelift links.
  • Consider labelling PRs (even just bug/enhancement/dependencies), which is the only thing that would let release.yml produce genuinely categorised notes. Without labels, "🏕 Changes" is the most honest heading available.

Workflow defect found, reported not fixed

create-release.yml:233-234 has its environment: release approval gate commented out on the pypi job — ## Specifying a GitHub environment is optional, but strongly encouraged followed by #environment: release — so the release publishes to PyPI with no manual approval. Out of scope here and left alone; flagging it for its own issue.

@JarryShaw
docs(github): review the non-workflow metadata under .github/
6331a45 
Requested by the owner; no issue tracks this.

- `release.yml` is live and stays. `create-release.yml:164` requests the
  generated notes and the action joins them after the body, so a pre-release
  carries them alone. Its catch-all was titled "Features" while 24 of the last
  40 merged pull requests were `fix` and 2 were `feat`, so it is now "Changes";
  the catch-all also moved last, so the dependency category no longer depends on
  an `exclude` to receive anything.
- `bug_report.md` gains the reproduction section it never had, asks for the
  commit when the reporter is on a checkout, marks the traceback optional since
  most defects here are silent, and drops the pinned `1.5.0b4` example.
- `ISSUE_TEMPLATE/config.yml` is new. `SECURITY.md` asks reporters not to file
  anything exploitable publicly, and the chooser offered no private route.
- Both issue templates now self-label; no issue after #576 carries a label.
- `PULL_REQUEST_TEMPLATE.md` replaces three purpose boxes that had no room for a
  `docs` or `test` change with the eight types `CONTRIBUTING.md` documents, and
  drops GitHub's retired `/search?q=` endpoint.
- `FUNDING.yml` loses GitHub's commented-out platform roster, `otechie` among
  them. `dependabot.yml` is unchanged.

Every YAML parses and matches GitHub's documented schema; every link resolves.
No changelog entry -- repository metadata is not user-visible, as in #613.
@JarryShaw

JarryShaw commented Sep 22, 2026

Copy link
Copy Markdown
Owner Author

Cross-review: NEEDS CHANGES → addressed, now GOOD TO GO

An independent cross-review ran on a different model (Sonnet) from the one that authored this PR (Opus), briefed to falsify rather than confirm, read-only. It returned NEEDS CHANGES on one claim. That claim was in this PR's description, not in the six changed files — the reviewer found nothing to change in any of them.

What it refuted, and the correction

"17 of 175 issues left its placeholder text in place verbatim", attached to the Additional context section.

Refuted, and the reviewer was right. Two different placeholders were conflated when this description was written:

Placeholder Issues retaining it verbatim
Add any other context about the problem here. (Additional context) 3 — #139, #166, #218
A clear and concise description of your system information. (System information) 17

The figure 17 was real but belonged to the other section. Re-derived independently and the numbers agree exactly, including the three issue numbers. The description has been corrected; the template edit it supported stands on its own merits and is unchanged.

Two further overclaims the reviewer flagged, both now fixed in the description:

  • "the documented idiom" — overstated. GitHub's own documentation example for a repo like this one uses the opposite form (catch-all first, with exclude: dependencies) — the very pattern this PR removed. The reviewer traced both orderings by hand and confirmed they produce an identical partition: no PR double-categorised, none dropped. So the old file was not broken, and the reorder is kept only because it drops a now-redundant exclude. The substantive fix — retitling 🏕 Features → 🏕 Changes — is independent of the ordering.
  • ci: wire the existing linters into CI as advisory checks #626 cited as precedent — it is still open, not merged, so it carries less weight than docs: repair the Code of Conduct's rendering and refresh CONTRIBUTING #613. Reworded.

No commit amend was needed: none of the three claims appears in the commit message.

What it confirmed independently

# Claim Verdict
1 release.yml is live; the pre-release fallback is real CONFIRMED — create-release.yml:121, :129-132, :137-140, :164 read verbatim. CHANGELOG.md's heading token is 1.5.0 and __version__ is 1.5.0b4, so the tokens already differ today and will differ for 1.5.0b5 — the fallback genuinely fires and release.yml alone determines those notes
2 Reorder is behaviourally sound CONFIRMED functionally (framing corrected above)
3 Label statistics — 0/20 PRs labelled; 24 fix/6 test/6 docs/2 feat/1 perf; 8/40 issues labelled, none above #576 CONFIRMED, exact — re-derived from scratch
4 Every path, anchor, target and URL resolves CONFIRMED, exact — all three CONTRIBUTING.md anchors (:60, :89, :107) with no slug collisions; all four Makefile targets (:79, :124, :134, :137); BOOLEAN_STATES['true'] is True so PCAPKIT_DEVMODE=true genuinely works; the 8 commit types at CONTRIBUTING.md:133 match the 8 new checkboxes exactly; all four new URLs return 200/302-to-login
5 New config.yml is schema-valid CONFIRMED
6 bug and enhancement labels exist CONFIRMED — a template naming a nonexistent label would have been a defect
7 FUNDING.yml live values preserved CONFIRMED — the three kept values are byte-identical to origin/main; every removed key had an empty value; otechie is absent from GitHub's current 12 documented platforms
8 Scope clean PASS — exactly the six files; nothing under .github/workflows/**
9 No-changelog decision honest CONFIRMED — changelog_md.py --check exits 0; #613's and #624's bodies confirm the convention is genuinely unsettled rather than cherry-picked
10 Prose spot-checks Mostly confirmed — 0/40 mention PCAPKIT_DEVMODE, 14 of 15 Dependabot PRs closed unmerged, 134/175 issues maintainer-filed, 0/20 PRs used the template. One miss: "12 of the last 39" human PRs lacking a docs/test box recomputed as 11, likely corpus drift

Stated limits of the review

  • Whether issues were filed via agents specifically is not observable through the API — maintainer authorship is confirmed, method is not.
  • Whether contact_links[].about is strictly required, and the no-file default for blank_issues_enabled, are not stated in GitHub's documentation — neither is something this PR asserts.
  • GitHub's release-notes generator was not executed live against the new release.yml; first-match-wins was reasoned from the documentation, not observed.

CI

Checks are QUEUED, not failing — the Actions queue is saturated by concurrent work on this repository. This change touches no code; the one gate that bears on it, Changelog drift, was verified locally (python util/changelog_md.py --check exits 0).

Verdict after the correction: GOOD TO GO. Unpublished judgement on merge remains the owner's.

@JarryShaw
JarryShaw merged commit 3881bf6 into main Sep 22, 2026
24 checks passed
This was referenced Sep 22, 2026
Closed
Merged
@JarryShaw JarryShaw added the docs Pull requests that change documentation only (docs: subject prefix) label Sep 22, 2026
@JarryShaw JarryShaw mentioned this pull request Sep 22, 2026
Closed
@JarryShaw
JarryShaw deleted the chore/github-metadata-cleanup branch September 23, 2026 02:38
@JarryShaw JarryShaw added the chore Maintenance work: tooling, repo hygiene, no library behaviour change label Sep 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

chore Maintenance work: tooling, repo hygiene, no library behaviour change docs Pull requests that change documentation only (docs: subject prefix)

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@JarryShaw