Skip to main content

Branch Naming Guidelines

Following our branch naming convention helps to keep things consistent and also encourages following the conventional commit method.

Branch name calculator

If you don't want to read through this page, you can simply use the interactive "branch name calculator" below 😉:

Ownership
Issue-based
Conventional Commit Based


Your branch name:

feat/add-xy

Reading this document​

Reading the EBNF grammar in this document

This document uses the EBNF language to describe a technical grammar for branch names.

This is quite easy to read:

  • [] = optional
  • {} = repeat 0..n times
  • <> = element defined somewhere else
  • "/" = literal content / in the name
  • <a> | <b> = either <a> or <b>

General Structure​

Overall, your branch names should have the following structure:

<branch name> ::= [<branch ownership prefix>] <branch content> ;

Branch owner prefix (optional)​

If you intend to work on the branch all by yourself, it's valuable to "claim ownership" within the branch name itself.

This both shows other contributors that they shouldn't work on this branch without your permission and shows maintainers whom to contact about the contents within the branch.

A branch ownership prefix consists of your GitHub username, followed by a /:

<branch ownership prefix> ::= <GitHub username> "/" ;

Branch content​

It's essential to, as short as possible, describe the content of the branch (i.e., the changes it attempts to make).

Within the Server State Ecosystem, we recommend using one of two ways:

<branch content> ::= <issue-based> | <conventional-commit-based> ;

Issue-based​

If an issue already discusses the details of what your branch changes, you should link to that issue within your branch name.

When you're working on an issue, please also make sure to assign yourself to the issue. That way, other contributors can see that you're already working on this issue.

<issue-based> ::= "issue-" <issue number> ;

<issue number> ::= <positive, whole number> ;

Conventional Commit based​

Alternatively, you can also describe the content directly in a "conventional commit like" structure.

tip

Describing branch names in a way that's similar to conventional commits is especially helpful as it already forces you to take on the "one change per branch" conventional commit mindset.

Instead of colons and scopes, we use slashes (/). Also, we don't care about breaking changes within the branch name, yet.

Therefore, a conventional commit based branch description should be structured like this:

<conventional-commit-based> ::= <conv-type> "/" [<conv-scope>] <description> ;

<conv-type> ::= "feat" | "fix" | "docs" | "chore" | "test" | "refactor" | "style" | "perf" ;
<conv-scope> ::= <scope-name> "/" ;
<description> ::= <valid-char> {<valid-char>} ;

<scope-name> ::= <valid-char> {<valid-char>} ;

<valid-char> ::= "a" | "b" | ... | "z" | "-" | "/" ;

where

  • <description> describes the actual change (e.g., add-send-function)
  • <scope-name> is a conventional commit scope present within the repository (cf. repo docs/guidelines for available scope names)

Examples​

Since EBNF can be a little bit ... abstract, let's take a look at a few examples.

For the following examples, we assume that your username is @githubuser.

Example: Fixing a long-discussed issue

A change has been discussed in issue #83 for quite a while. You're contributing a fix on your branch.

githubuser/issue-83
Example: Working on an enormous change together

An extensive restructuring of the CLI is needed. This is too big to be discussed in a single issue and instead covers multiple issues.

Multiple contributors are working on this branch.

feat/cli/restructure-the-cli
Example: A minor fix

You've spotted a bug in the CLI. Writing an extensive issue would cost you more time than just quickly changing the line yourself.

You, therefore, omit opening an issue and instead commit the change immediately.

githubuser/fix/cli/fix-args-parsing

See also​

Conventional Commit Types »./conventional-commit-types