You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs(adr): enforce issue traceability on the pull request, not the branch name #593
Validate Branch Name became a blocking required status check after #586 and #591. It requires an issue id in the branch name, which decisions/0019-trunk-on-main-default.md specifies as feature-<id>, bug-<id>, hotfix-<id>.
Measured against what that rule is actually a proxy for, traceability from a
pull request back to an issue, it filters on the wrong thing.
Evidence
Last 60 merged pull requests into z-shell/.github:
Branch shape
Closes an issue
Mentions one only
No reference at all
Has issue id (18)
12
6
0
No issue id (42)
10
22
10
The id is a perfect predictor: all 18 branches carrying one referenced an
issue. It is a poor filter: it rejects 42 pull requests to catch the 10 that
reference nothing, blocking 32 that were traceable and simply did not put the
number in the branch name.
Meanwhile the thing the rule stands in for, a reference on the pull request, is
checked by nothing at all.
"Mentions one only" counts any #N in the body, so some of those 32 are
passing references rather than real links. That weakens the count without
changing the conclusion.
Proposal
Draft an ADR amending ADR-0019 on one clause:
Enforce traceability directly, with a required check that the pull request
closes or references an issue, with an explicit exemption for genuinely
issue-free work such as gitlink bumps and dependency updates.
Relax Validate Branch Name to a shape check, so the issue id is
recommended rather than mandatory.
Everything else in ADR-0019 stands: trunk on main, the zinext exception,
the class table, and the migration steps.
Scope
This issue covers the ADR only. The workflow implementation follows as separate
work once a maintainer accepts or rejects the record. Related: #592, which
proposes test coverage for the commit-lint patterns those checks live in.
Resolved. #600 moved the traceability check onto the pull request (Validate Issue Link), #601 relaxed Validate Branch Name to the type shape, and decisions/0022-issue-traceability-on-pull-requests.md records the decision; AGENTS.md now states that the issue identifier in a branch name is recommended, not required. Verified today against the active main ruleset on z-shell/.github: the four required contexts are Validate Commits, Validate PR Title, Validate Branch Name, and Validate Issue Link. Closing as completed.
Activity
docs(adr): accept ADR-0022
docs(adr): accept ADR-0022 issue traceability on pull requests (#594)
ss-o commentedon Sep 18, 2026
Resolved. #600 moved the traceability check onto the pull request (
Validate Issue Link), #601 relaxedValidate Branch Nameto the type shape, anddecisions/0022-issue-traceability-on-pull-requests.mdrecords the decision;AGENTS.mdnow states that the issue identifier in a branch name is recommended, not required. Verified today against the activemainruleset on z-shell/.github: the four required contexts areValidate Commits,Validate PR Title,Validate Branch Name, andValidate Issue Link. Closing as completed.