DecisionUse [ticket-id]--[short-description] in feature branch names

accepted

Omitting key information in branch names can cause confusion over the purpose of a branch.

Decision

Use [ticket-id]--[short-description] as the branch name when creating a new feature branch. If a ticket doesn't exist, use a consistent keyword in place of a ticket ID. Suggested keywords include:

  • NOTICKET: general purpose prefix for any time there is no ticket.
  • 0: An alternative general purpose prefix.
  • HOTFIX: used for a branch containing a hotfix that does not have an associated ticket.

Do not use forward slashes (/) in branch names as this can cause confusion and errors when trying to interact with branches sharing prefixes. For example, it is not possible to create a branch called new-homepage if another branch called new-homepage/fix-heading exists. This can also cause errors when pulling if a new branch conflicts with a local-only branch.

Examples

Here are some examples of good branch names:

  • wta-249--scaffold-alert-content-type
  • wta-NOTICKET--fix-tests-in-head
  • wta-0--fix-tests-in-head
  • HOTFIX--remove-has-krumo
  • 143--git-naming-conventions
  • NOTICKET--troubleshoot-ci

Consequences

Teams can choose to implement pull-request checks or pre-commit hooks that validate branch names based off of a simple regular expression. For example, the following command would fail if the branch name did not contain two dashes:

if ! git rev-parse --abbrev-ref HEAD | grep -qE '^main$|\-\-'; then
  echo "Please use the format [ticket-id]--[short-description] in branch names" >&2
  exit 1
fi

Developers can use branch names to automate commit messages and other common tasks, such as in this git commit message example.


Andrew Berry, Chris DeLuca, David Burns, James Sansbury, Mateu Aguiló Bosch, Marcos Cano, Matthew Oliveira, Owen Bush, Sally Young, Salvador Molina Moreno

Decided on