Skip to main content

Branching Strategy

Develop Branch​

The develop branch on your local repository should have the upstream branch set on the remote you are trying to pull from. This allows Git to know which remote branch to pull changes from.

To change from the main branch, you need to set an upstream branch for develop. You have two primary options:

  1. Set the upstream branch and pull in one command:

    git pull origin develop

    This command will pull changes from the develop branch on the origin remote, and it will automatically set this as the tracking branch for future pulls.

  2. Set the upstream branch separately and then pull:

    git branch --set-upstream-to=origin/develop develop
    git pull

    The first command sets the origin/develop branch as the upstream for your local develop branch. The second command then pulls changes from the set upstream branch.

Choose the method that you find more convenient. Once the upstream is set, future git pull operations will not require specifying the remote and branch.

Git Flow​

To implement a GitFlow branching strategy on GitHub and adjust your workflows accordingly, follow these steps:

1. Set Up GitFlow Branching Strategy​

Branches in GitFlow:

  • main: Contains production-ready code. Only direct commits due to hotfixes or merges from release branches.
  • develop (or dev): Integrates feature branches and is used for testing. Eventually, it gets merged into main for releases.

First Goal: Development Branch

  • Create develop Branch:

    • Create a develop branch by branching off main:

      git checkout main
      git checkout -b develop
      git push origin develop

  • Protect develop Branch:

    • Go to your repository on GitHub.
    • Navigate to Settings > Branches.
    • Set up protection rules for develop similar to main. This often includes:
      • Requiring pull requests before merges.
      • Passing status checks.
      • Optional: Require a specific number of approving reviews.

  • Maintain main Protection: Continue protecting the main branch, as it represents production code.

2. Modify GitHub Workflows​

You'll need adjustments based on where you want these workflows to trigger, especially with the introduction of the develop branch.

ci.yml Workflow​

Modify it to run on pushes to or pull requests targeting develop:

name: CI

on:
  push:
    branches:
      - develop
  pull_request:
    branches:
      - develop

publish-packages.yml Workflow​

Typically, this workflow remains scoped to main because you usually want to publish packages based on production-ready code:

  • Optionally, introduce release branch handling:
on:
  push:
    branches:
      - main
      - 'release/**'   # Triggers on release branches

deploy-docs.yml Workflow​

This could be configured similarly to ensure deployments based on the content in main, as docs should generally reflect production:

on:
  push:
    branches: ['main']

3. Preparing for Releases​

  • Release Branch:

    • When you're ready to prepare for a new production release, create a release branch from develop. E.g., release/v1.0.
    git checkout develop
    git checkout -b release/v1.0

  • Tagging:

    • Once a release branch is tested and ready, merge it into main.
    • Tag releases in main with version numbers:
    git checkout main
    git merge release/v1.0
    git tag -a v1.0 -m "Release version 1.0"
    git push origin main --tags

  • Merge Back:

    • Merge release back into develop after releasing to include any release branch changes in ongoing development.

With these setups and changes in place, GitFlow will help manage development, releases, and production code effectively.