TimZander / TimZander/claude

Add branch-name validation hook to enforce Branch Naming standard

Open
#103 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
0
Forks
1
Avg merge
1d 3h
Merged PRs (30d)
7

Description

Goal

Machine-enforce the branch naming convention introduced in #5 (branches/<issue-number>-<kebab-case-slug> or branches/<kebab-case-slug>) so compliance does not depend on the developer or Claude remembering the rule.

Current Behavior

After #5 merges, the convention lives in `standards/CLAUDE.md` as advisory text. Existing hooks (`hooks/pre-push`, `hooks/pre-commit`) enforce main-push protection and commit-email validation but do not validate branch names. A developer who creates a branch like `feature/foo` or `my-work` can push it without any feedback.

Proposed Solution

Extend the global `pre-push` hook (or add a companion hook) to reject pushes from branches whose name does not match the documented format. Specifically:

  • Accept: `branches/-` where `` is one or more digits and `` is lowercase letters, numbers, and hyphens.
  • Accept: `branches/` (no numeric prefix) for branches that have no tracked issue.
  • Reject with a helpful error message pointing at the standards doc when the name does not match.
  • Skip validation on `main`, `master`, and any branch matching names that predate this rule, to avoid blocking legitimate pushes to already-named branches (list can live in the hook as a regex).

Add a per-repo opt-out file (e.g., `.allow-any-branch-name`) following the same pattern as the existing `.allow-push-main` escape hatch, so personal projects or forks can skip enforcement.

Acceptance Criteria

  1. Pushing from a compliant branch (`branches/123-my-feature` or `branches/my-feature`) succeeds unchanged.
  2. Pushing from a non-compliant branch (`feature/foo`, `my-work`) is rejected with an error message that quotes the expected format and links to `standards/CLAUDE.md`.
  3. The existing main-push protection and commit-email validation are unaffected.
  4. A repo containing `.allow-any-branch-name` in its root skips the branch-name check.
  5. `hooks/hooks.json` is updated if a new hook file is introduced.
  6. `setup-env.sh` and `setup-env.ps1` install the updated hook on re-run.

Open Questions

  • Should the hook also validate that `Closes #N` / `Fixes #N` appears in the latest commit message when the branch name contains an issue number? That feels more intrusive; start with branch-name-only and consider extending later.
  • Should the hook run on `pre-commit` (catches the problem earlier) or `pre-push` (fewer false positives on in-progress branches that get renamed)? `pre-push` is probably the right trade-off.

Related

  • #5 — introduces the Branch Naming and PR Linking standard this hook would enforce.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading hooks/pre-push and hooks/pre-commit to understand the existing protections, then inspect hooks/hooks.json, setup-env.sh, and setup-env.ps1 for installation behavior. Implement branch-name enforcement with the documented opt-out and legacy exceptions, preserving the existing checks. Verify the compliant, rejected, main/master, opt-out, and installer cases against the acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell, shell
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.