Gitflow

Gitflow

This skill covers the Gitflow branching model: the two long-lived branches, the three supporting branch types, commit message conventions, semantic versioning, and the release and hotfix processes.

Workflow for a Feature Change

1. Sync develop — Run git checkout develop && git pull origin develop so the feature branches from the latest development state.
2. Create the feature branch — Run git checkout -b feature/123-user-authentication, using the naming convention feature/[issue-id]-descriptive-name.
3. Commit with conventional messages — Use type(scope): description for every commit (see Commit Messages below).
4. Rebase or merge develop in — Before opening a PR, bring the branch up to date: git fetch origin && git rebase origin/develop (or merge, per team convention).
5. Open a pull request into develop — Require at least one approval and passing CI checks; never commit directly to develop.
6. Merge and clean up — After merge, delete the feature branch both locally and on the remote: git branch -d feature/123-user-authentication && git push origin --delete feature/123-user-authentication.

Main Branches

main (or master)

• Contains production-ready code only.
• Never commit directly to main.
• Only accepts merges from hotfix/* branches or release/* branches.
• Must be tagged with a version number after every merge (e.g. git tag -a v1.2.0 -m "Release 1.2.0").

develop

• The main integration branch; contains the latest delivered development changes.
• Source branch for all feature/* branches.
• Never commit directly to develop — all changes land through pull requests.

Supporting Branches

feature/*

• Branch from: develop.
• Merge back into: develop.
• Naming convention: feature/[issue-id]-descriptive-name (e.g. feature/123-user-authentication).
• Must be up to date with develop before opening a PR.
• Delete after merge.

release/*

• Branch from: develop.
• Merge back into: main and develop.
• Naming convention: release/vX.Y.Z (e.g. release/v1.2.0).
• Scope is limited to bug fixes, documentation, and release-oriented tasks — no new features.
• Delete after merge.

hotfix/*

• Branch from: main.
• Merge back into: main and develop.
• Naming convention: hotfix/vX.Y.Z (e.g. hotfix/v1.2.1).
• Reserved for urgent production fixes only.
• Delete after merge.

Commit Messages

Use Conventional Commits format: type(scope): description.

Example:

feat(auth): add refresh-token rotation

fix(orders): prevent duplicate charge on retry

chore(deps): bump lodash to 4.17.21

Semantic Versioning

Given a version MAJOR.MINOR.PATCH:

• MAJOR — incremented for incompatible/breaking API changes.
• MINOR — incremented for backwards-compatible new functionality.
• PATCH — incremented for backwards-compatible bug fixes.

Pull Request Rules

1. All changes must go through pull requests — no exceptions for main or develop.
2. Minimum of one required approval before merge.
3. All CI checks must pass.
4. No direct commits to protected branches (main, develop).
5. The branch must be up to date with its target before merging.
6. Delete the branch after merge (both local and remote copies).

Branch Protection Rules

Apply to both main and develop:

• Require pull request reviews before merging.
• Require status checks to pass before merging.
• Require branches to be up to date before merging.
• Include administrators in the restrictions (no bypassing rules with elevated permissions).
• No force pushes.
• No branch deletions.

Release Process

1. Create a release branch from develop: git checkout -b release/v1.2.0 develop.
2. Bump version numbers in package manifests / changelogs.
3. Fix any release-specific issues (docs, last-minute bugs) — do not add new features.
4. Open a PR from the release branch into main.
5. After merge to main:
   • Tag the release: git tag -a v1.2.0 -m "Release 1.2.0" and push the tag.
   • Merge main back into develop so develop has the release commit and tag.
   • Delete the release branch.

Hotfix Process

1. Create a hotfix branch from main: git checkout -b hotfix/v1.2.1 main.
2. Fix the production issue with the smallest possible change.
3. Bump the patch version.
4. Open a PR from the hotfix branch into main.
5. After merge to main:
   • Tag the release: git tag -a v1.2.1 -m "Hotfix 1.2.1" and push the tag.
   • Merge main back into develop so the fix isn't lost in the next release.
   • Delete the hotfix branch.