Summary
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 zi next 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.
Summary
Validate Branch Namebecame 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.mdspecifies asfeature-<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: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
#Nin the body, so some of those 32 arepassing references rather than real links. That weakens the count without
changing the conclusion.
Proposal
Draft an ADR amending ADR-0019 on one clause:
closes or references an issue, with an explicit exemption for genuinely
issue-free work such as gitlink bumps and dependency updates.
Validate Branch Nameto a shape check, so the issue id isrecommended rather than mandatory.
Everything else in ADR-0019 stands: trunk on
main, thezinextexception,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.