From Conventional Commits to Conventional Branch

Naming branches can be just as challenging as naming variables. In fact, naming anything is a challenging task.

A few years ago, I came across the Conventional Commits project. I love this project because it has significantly improved the readability of commit messages. It has helped me say goodbye to messy git logs (yes, you guessed it, I am the kind of developer who always does git rebase).

While there are some widely used conventions for branch naming, such as starting feature branches with feature/ and bug fix branches with bugfix/, there isn't a convention as widely recognized as Conventional Commits for branch naming. Until I found the Conventional Branch.

Let me share the specification of the Conventional Branch first.

---

Specification

Branch Naming Prefixes

The branch specification by describing with feature/, bugfix/, hotfix/, release/ and chore/ and it should be structured as follows:

<type>/<description>

• main: The main development branch (e.g., main, master, or develop)
• feature/: For new features (e.g., feature/add-login-page)
• bugfix/: For bug fixes (e.g., bugfix/fix-header-bug)
• hotfix/: For urgent fixes (e.g., hotfix/security-patch)
• release/: For branches preparing a release (e.g., release/v1.2.0)- chore/: For non-code tasks like dependency, docs updates (e.g., chore/update-dependencies)

Basic Rules

1. Lowercase and Hyphen-Separated: Always use lowercase letters, and separate words with hyphens. For example, feature/new-login or bugfix/header-styling.
2. Alphanumeric and Hyphens Only: Use only lowercase letters (a-z), numbers (0-9), and hyphens. Avoid special characters like spaces, punctuation, and underscores.
3. No Consecutive Hyphens: Ensure that hyphens are used singly, with no consecutive hyphens (e.g., feature/new-login, not feature/new--login).
4. No Trailing Hyphens: Do not add a hyphen at the end of the branch name. For instance, use feature/new-login instead of feature/new-login-.
5. Clear and Concise: Make branch names descriptive but concise. The name should clearly indicate the work being done.
6. Include Jira (or Other Tool) Ticket Numbers: If applicable, include the ticket number from your project management tool to make tracking easier. For example, for a ticket T-123, the branch name could be feature/T-123-new-login.

---

The conventions in this project are quite close to my ideal way of naming branches. The branch prefixes in the conventions are similar to the types in Conventional Commits, so I don't need to spend extra time learning a new naming pattern. The naming format is simple and easy to understand, without causing additional reading burden.

You might notice that GitHub branch searching is case-sensitive because Git is designed like this. foo and FOO are different branches! Always using lowercase letters will make your life easier. Only using alphanumeric characters and - will increase readability.

The benefit of using branch type prefixes is that some GUI tools will organize branches by type.

I think #3 and #4 can be merged. #6 shouldn't be part of the basic rules, as not every dev team uses a system like Jira to track their tasks and have a ticket number. The conventions should be general enough to be widely accepted.

---

These rules are not Golden Rules. If you decide to apply Conventional Branch to your project, you might need customization. For example, I will create some branches for my own usage when doing technical exploration. With this pattern: louis/tech-explor.

Conventional Branch is a good start to establish branch naming rules for Git. What's your opinion? Welcome to share your thoughts in the comments!