Skip to content

Git workflow

Jump to bottom
Jason Li edited this page Dec 9, 2025 · 3 revisions

Git branches are pointers to work done at a particular point in time, so they are cheap, and their use is to assist us with managing the progress of development, release, and production.

This document outlines a structured Git workflow based on the industry-standard Gitflow model. This strategy is designed to ensure strict version control, maintain a stable production environment, and allow for parallel development of features and bug fixes.

1. Branch Hierarchy and Definitions

This policy defines strict roles for the three primary branches.

main (Production)

Purpose: The single source of truth for production-ready code.

Stability: This branch must always be stable and deployable.

Policy Rules:

  • No Direct Commits: Developers are strictly forbidden from committing directly to main.

  • Merge Source: Only release branches or hotfix branches may be merged into main.

  • Tagging: Every merge into main must be accompanied by a version tag (e.g., v1.0.1).

development (Integration)

Purpose: The integration branch for features and the "next release" staging area. It contains the complete history of the project.

Stability: generally stable (builds should pass), but may contain minor bugs not yet fixed for production.

Policy Rules:

  • No Direct Commits: Direct commits are discouraged; changes should come via Pull Requests (PRs) from feature branches.

  • Sync: This branch serves as the base for all new feature development.

release (Staging/Stabilization)

Purpose: A temporary branch used to prepare code for a new production deployment. It allows for "code freeze" where only bug fixes and documentation tasks occur.

Naming Convention: release/vX.X.X (e.g., release/v1.2.0).

Policy Rules:

  • Creation: Created from development when the team decides the code is feature-complete for the next cycle.

  • Scope: No new features can be added here. Only bug fixes, documentation generation, and release-oriented tasks.

  • Termination: Once deployment is confirmed, this branch is merged into both main (for production) and back into development (to ensure future releases have the fixes).

2. Supporting Branches

While not permanent, these branches are critical to the workflow policy.

feature/* Branches:

Source: Must branch off development.

Destination: Must merge back into development.

Naming: feature/jira-ticket-id-description or feat/short-description.

Policy: Features should be small and focused. Long-lived feature branches are discouraged to prevent "merge hell."

hotfix/* Branches:

Source: Must branch off main. (This is the only branch that originates from main).

Destination: Must merge into both main and development.

Purpose: Critical bug fixes for production that cannot wait for the next scheduled release.

3. The Workflow Lifecycle

Phase 1: Feature Development

  1. Developer creates a feature branch from development.

  2. Work is committed to the feature branch.

  3. A Pull Request (PR) is opened to merge the feature into development.

  4. Code Review: At least one peer review is required. CI/CD tests must pass.

  5. Feature is merged into development.

Phase 2: Release Preparation

  1. When enough features are accumulated, a release branch is created from development.

  2. A "Code Freeze" is announced. No new features are accepted.

  3. QA testing occurs on the release branch.

  4. Bug fixes are committed directly to the release branch.

Phase 3: Deployment

  1. The release branch is merged into main.

  2. The merge commit on main is tagged with the version number.

  3. The release branch is also merged back into development to ensure any bug fixes made during the release phase are saved.

4. Further Reading

Atlassian's Git Workflow Tutorial

Clone this wiki locally