Skip to content

docs(adr): enforce issue traceability on the pull request, not the branch name #593

Description

@ss-o

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:

  1. 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.
  2. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:metaOrganization-wide policy, templates, or meta-repo work.type:docsDocumentation-only work.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions