Skip to main content

Branch Naming Enforcement

  • Status: Accepted
  • Author: Willem Paul
  • Deciders: Abyss Team
  • Date: 05/07/2024

Context​

Our Workspace Setup guide mentions that all branches should be named according to our convention; every branch name should start with story/<Rally US number>, defect/<Rally defect number>, refactor/, or release/. Our CI workflows do validate branch names, but adding a pre-commit hook will allow us to catch errors even sooner.

Decision​

The Abyss team will add a Git pre-commit hook using Husky that will prevent commits if the branch name does not match our convention. This hook should be very simple, just checking the branch name against a regular expression.

Alternatives Considered​

Volcan's git-branch-name-enforcer is already part of our workflow (called from within the volcan-aws-web-static-develop workflow), so we don't necessarily need to add a hook. As mentioned above, though, adding a hook would allow us to catch incorrect branch names sooner, but there is a consequence of this as well (see below).

Consequences​

Pros:

  • Enforce branch naming automatically to prevent broken builds or having to delete and recreate branches
  • Easier PR review process

Cons:

  • Adding new prefixes will require an update to the hook, but this is an insignificant amount of work

  • Until and unless we modify the workflow we use to build the application for PRs, we are restricted to just to following prefixes allowed by the aws-web-static-develop:

    • story/
    • defect/
    • refactor/
    • release/
    • feature/

    This would involve working with the Volcan team to expose the required parameters from git-branch-name-enforcer through the volcan-aws-web-static-develop and aws-web-static-develop workflows.

    Note: The pr-validation workflow contained within this is not currently required to pass, so we can maintain our own list of allowable prefixes. The pre-commit hook included with the initial ADR PR allows the following list:

    • adr/
    • ci/
    • copilot/
    • defect/
    • design/
    • docs/
    • refactor/
    • release/
    • story/
    • testing/

    The copilot/ prefix is allowed because the GitHub Copilot coding agent creates its branches with a fixed, non-configurable copilot/ prefix. Since contributors may need to pull and commit to a branch the agent opened (e.g. an automated dependency upgrade PR), the prefix must pass the hook.

Future Considerations​

Most of the time, the release/ branches are created automatically from a pipeline. There may be some occasions when a developer would need to create one manually, however, so it may be worth investigating whether or not we can restrict manual creation of these branches to certain users. This could be done initially, but isn't high-priority.

Notes​

  • Developers will need to run

    pnpm install

    after pulling main in order to install Husky locally. Beyond that, there should be no other setup necessary.

Changelog​

  • 05/07/2024: Removed git-branch-name-enforcer from alternatives; added new consequence regarding this
  • 05/16/2024: Updated to include current branch name prefixes
  • 05/22/2024: Added note about Husky and running npm install on the first pull
  • 03/31/2026: Update notes to use pnpm instead of npm
  • 06/20/2026: Added copilot/ prefix (GitHub Copilot coding agent uses a fixed, non-configurable copilot/ branch prefix); also documented the design/ prefix that was already enforced by the hook
Table of Contents