Branch Management

Hero image for Branch Management

Our methodology is mostly inspired from git-flow which basically allows to separate works by branch types: feature, bug, chore and release.

Formatting

  • Use lowercase and kebab-case for branches names.

    # Bad
    feature/list_job_positions
    Bug/userResetPassword
      
    # Good
    feature/list-job-positions
    bug/user-reset-password
    
  • Use the forward slash / to separate the branch type from the branch title.

    # Bad
    feature-list-job-positions
    bug_user-reset-password
      
    # Good
    feature/list-job-positions
    bug/user-reset-password
    

Naming

  • Find a balance between conciseness and descriptiveness for branch titles. Think that you and other developers can distinguish easily each branch.

    # Bad
    feature/as-a-user-i-can-logout
    bug/as-an-admin-when-i-select-a-menu-item-i-see-a-highlight
      
    # Good
    feature/user-logout
    bug/admin-menu-item-highlight
    
  • Prefix the branch title with the backlog item ID when using project management tools such as Clubhouse and JIRA. The aforementioned tools require it for their Git integration to function. While other tools rely, such as Pivotal Tracker, rely on the commit message content to include the backlog item ID.

    # Bad
    ch-6862/feature/list-job-positions
      
    # Good
    feature/ch-6862-list-job-positions
    

Default Branches

  • By default, there must be 2 branches: main and develop. Both branches must be created when setting up the code repository.

  • The main branch is the version in production.

  • The develop branch is the version currently on the staging environment.

  • No one should commit directly to either the main or develop branches.

  • Avoid commit history rewrites on either the main or develop branch at all costs as it could leave the project in a dire state.

Working Branches

  • All feature, bug and chore branches must be checked out locally from the develop branch. By avoiding branching more than one node away from the main branch, we can easily avoid complex conflicts and rebasing which can take hours or days to solve.

  • The definition of what constitutes a feature, bug or chore depends on the user story type. No code should be committed if there is not a user story for the tasks at hand.

  • Once merged, feature, bug and chore branches should be deleted to keep only the default and active branches.

Releases Branches

  • Release branches must be checked out locally from the develop branch.

  • Releases branches are required when opening a pull request to merge code into the main branch. No code is merged directly into the main branch.

  • The name for release branches must contain the corresponding semantic version number.

    # Bad
    release/1.0
    release/v1.0
      
    # Good
    release/1.0.0