BLogic Systems

Git Branch & Workflow Convention

Last updated on 

1. Branch meanings

develop

  • Acts as the main working branch.
  • All new work must start from develop:
    • New feature branches (feat/...)
    • Hotfix branches (hotfix/...)
  • Always up to date with the latest approved changes that are safe to integrate.
  • No one commits directly to develop on remote — changes go through Pull Requests (PRs).

Example:

git checkout develop
git pull origin develop
git checkout -b feat/ticket-42_create-new-button-component

staging

  • Used only for QA testing.
  • Contains features that are:
    • Completed by developers
    • Not yet released to main
  • Rules:
    • Do not create branches from staging.
    • Do not merge staging into any other branch.
    • Only merge feature/hotfix branches into staging for QA verification.

Conceptually:
develop = source of truth for code
staging = playground for QA to test features before release

main

  • Represents production-ready code.
  • Only updated via PR from develop.
  • Used as the base for release tags.

Flow:
develop → (PR) → main → (tag) → release

2. Development workflows

2.1 QA testing workflow

  1. Create a feature/hotfix branch from develop:git checkout develop
    git pull origin develop
    git checkout -b feat/ticket-42_create-new-button-component
  2. Develop freely:
    git commit -m "Add base button component"
    git commit -m "Add button variants and tests"
    • Commit as many times as needed on your feature branch.
  3. Push and open PR into develop:git push origin feat/ticket-42_create-new-button-component
    • Open a PR:
      from feat/ticket-42_create-new-button-component
      into develop
    • Add reviewers.
    • Add label: staging (indicates this branch is ready for QA testing on staging).
  4. Prepare staging for QA to test this feature:
    • When QA needs to test:git checkout staging
      git pull origin staging
      git merge feat/ticket-42_create-new-button-component
      # or cherry-pick specific commits if needed
      # git cherry-pick <commit-hash>
      git push origin staging
    • Resolve conflicts (if any) during the merge.
    • QA tests the feature on environment deployed from staging.

Key points:

  • staging is built by merging tested feature branches into it.
  • PR still targets develop; staging is just for QA, not for code review source of truth.

2.2 Release workflow

Once QA is done and all requested changes are applied:

  1. Update PR status:
    • Change label from staging → ready to release.
  2. Squash commits in the feature branch into a single clean commit:
    • Result: the PR into develop will show one clean commit for this feature.
      git fetch -a
      git checkout feat/ticket-42_create-new-button-component
      git rebase -i origin/develop # squash local commits into one
      git push -f origin feat/ticket-42_create-new-button-component
  3. Merge into develop:
    • The team lead (or responsible reviewer):
      • Reviews the PR.
      • Uses "Rebase and merge" for the PR into develop.
    • After the PR is merged:
      • Delete the feature branch from remote.
  4. Prepare release from develop to main:
    • Team lead creates a PR:
      from develop
      into main
    • Reviews changes if needed (final sanity check).
  5. Merge into main with a merge commit:
    • Use a normal merge commit.
    • Do NOT use "Rebase and merge" for develop → main.
  6. Create a release tag on main:git checkout main
    git pull origin main
    git tag -a v1.2.0 -m "Release v1.2.0 - button component, bug fixes"
    git push origin v1.2.0
    • After the PR is merged:
    • Create a tag on the latest main commit.