Git Fundamentals and Workflow: A Complete Guide from Principles to Team Collaboration

In software development, a clear workflow is the cornerstone of efficient collaboration and stable releases. This article summarizes a Git workflow that has been validated in multiple projects. It is suitable for both rapid iteration by individual developers and scaled-up code collaboration by teams. The core design follows three principles: three-tier environment isolation, semantic versioning, and fast rollback capability.

Git Working Principles Basics

Before diving into workflows, understanding Git's basic working principles is crucial for understanding subsequent processes.

Git's Four Working Areas

Local Working Directory ──→ Staging Area ──→ Local Repository ──→ Remote Repository (GitHub)
    📁          📦         🗄️         ☁️

1. Working Directory: Where you actually edit files
2. Staging Area: Temporarily stores changes about to be committed
3. Local Repository: Database storing complete project history
4. Remote Repository: Shared repository hosted on platforms like GitHub/GitLab

Core Command Quick Reference

Typical Work Cycle

vim main.py

git status

git add main.py

git commit -m "feat: add new feature"

# 5. Push to remote repository
git push origin main

# 6. Pull others' updates
git pull origin main

After understanding these basic concepts, we will introduce practical workflows suitable for different team sizes.

Overview

This guide contains two working modes:

1. Single-person Mode (iterate directly on development) — Fast, simple, suitable for project initial stage or personal projects
2. Multi-person Collaboration Mode (feature branches + Merge Request) — More standardized, reviewable, reduces interference, suitable for team collaboration

Can upgrade according to team size at any time; recommended to enable multi-person collaboration part when second developer joins or releases are frequent.

Common principle: Three-tier environment + Semantic versioning + Rollback capability.

Environment and branch correspondence:

• DEV: development
• QUAL: master
• PROD: release-* (regex match)

Single-person shortest path: development → master → release-*. Multi-person collaboration path: feature-* → development → master → release-*.

Branch and Environment Mapping

Note: The above domains are examples only, please replace with your actual development, test and production environment addresses.

Runtime variable: APPSTORE_ENV = dev / qual / prod.

Single-person Mode Workflow (For single developer stage)

1. Daily Development (development)

git checkout development
git pull
# Modify code
git add .
git commit -m "feat: describe this change"
git push  # Trigger DEV deployment

Perform local/DEV smoke test: mainly focus on service startup, key pages or API returning normally.

2. Advance to QUAL (master)

First time without master:

git checkout development
git pull
git checkout -b master
git push -u origin master

Each subsequent release to QUAL:

git checkout development
git pull
git checkout master
git pull
git merge development   # Single-person mode direct merge
# Resolve conflicts (if any) then:
git push  # Deploy to QUAL

Do near-production validation in QUAL: network policy, permissions, performance, data correctness.

3. Release to PROD (release-*)

git checkout master
git pull
git checkout -b release-1.0.1
git push -u origin release-1.0.1  # Deploy to PROD
# Tag version (recommended)
git tag -a v1.0.1 -m "Release v1.0.1"
git push --tags

After completion, update RELEASE.md with new version notes.

4. Hotfix (Production issue found)

Fix directly on corresponding release-* branch:

git checkout release-1.0.1
git pull
# Make fix
git add .
git commit -m "fix: fix production xxx issue"
git push  # Immediately update PROD

Then sync back to other branches to avoid code drift:

git checkout master
git pull
git merge release-1.0.1
git push

git checkout development
git pull
git merge release-1.0.1
git push

5. Rollback to Old Version

If new version is unstable:

git checkout release-1.0.0
# Confirm code is correct
git push   # Re-trigger deployment (specific behavior depends on platform)

Extreme case to force current release back to old commit:

git checkout release-1.0.1
git reset --hard v1.0.0
git push -f

Single-person Mode Common Auxiliary Commands

# View commit brief history
git log --oneline --decorate --graph --all
# Branch differences
git diff master..development
# Current branch
git branch --show-current

Single-person Mode Minimal Checklist

• Develop and push verification on development
• After code is stable, merge to master deploy QUAL
• After QUAL validation passes, create release-x.y.z deploy PROD
• Tag & update RELEASE.md
• Monitor production; hotfix or rollback if necessary

Version Naming and Tags

• Branch: release-MAJOR.MINOR.PATCH
• Tag: vMAJOR.MINOR.PATCH
• PATCH: Bug fixes or minor adjustments; MINOR: New compatible features; MAJOR: Breaking updates (requires migration scripts and rollback plan).

Resource Configuration Recommendations (K8S)

resources:
  requests:
    memory: 300Mi
  limits:
    memory: 750Mi
    cpu: 750m

Don't set CPU requests; observe if memory peak approaches limit.

Environment Difference Example Code

import os
APP_ENV = os.getenv("APPSTORE_ENV", "dev")

if APP_ENV == "dev":
    DEBUG = True
    DB_FILE = "sqlite_dev.db"
elif APP_ENV == "qual":
    DEBUG = False
    DB_FILE = "sqlite_qual.db"
else:  # prod
    DEBUG = False
    DB_FILE = "sqlite_prod.db"

When to Switch to Multi-person Workflow?

Should switch to feature branches when any of the following occurs:

• Second developer joins
• Release frequency increases causing DEV to be frequently overwritten
• Need systematic code review
• Need parallel development of multiple features without interference

Multi-person Workflow Core Differences (Summary)

Can copy this file content when migrating to multi-person mode, remove single-person parts, and link in README.

High frequency, small steps, rollback capability; keep RELEASE.md synchronized with actual deployment.

Multi-person Collaboration Mode Workflow (feature branch workflow)

Objectives

In multi-person parallel development: isolate incomplete work, reduce risk of mutual deployment/test overwriting, introduce code review and quality gates, facilitate rollback and audit.

Branch Types and Human Semantics

Detailed Lifecycle Steps

1. Planning: Use Issues or task board to break down requirements; establish naming conventions (e.g. feature-import-parquet).
2. Create feature branch:

git checkout development
git pull
git checkout -b feature-import-parquet
git push -u origin feature-import-parquet

3. Development and local validation: Run unit tests/manual acceptance; create draft MR if needed for early feedback from others.
4. Code review (Merge Request): feature-* -> development, must meet:

• Pass automated tests
• At least 1 Reviewer approval
• No blocking comments

5. Auto-deploy DEV after merge: Perform centralized smoke test (UI, API, logs, resources).
6. After multiple features aggregate and reach "release candidate" condition → Establish release freeze point: MR development -> master; disable non-critical feature merges during freeze period.
7. QUAL validation: Security, permissions, performance, resources, compatibility; if fails: fix in new feature-* then cycle again.
8. Create production branch:

git checkout master
git pull
git checkout -b release-1.2.0
git push -u origin release-1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push --tags

9. Production monitoring: Logs, error rate, memory, restart count; hotfix if necessary. (hotfix-*)
10. Hotfix process:

git checkout release-1.2.0
git pull
git checkout -b hotfix-export-null-bug
# After fix
git add .
git commit -m "fix: handle null value in export causing exception"
git push -u origin hotfix-export-null-bug
# MR hotfix-export-null-bug -> release-1.2.0 review
# After merge production updates, then sync:
git checkout master && git pull && git merge release-1.2.0 && git push
git checkout development && git pull && git merge release-1.2.0 && git push

11. Rollback: If new release is unstable, switch back to old release-* branch; or use Tag to force reset.

Review Guidelines (Checklist)

CI/CD Recommended Gates

1. feature branch: Run fast unit tests + linter
2. development merge: Run extended test matrix (examples/datasets)
3. master merge: Security scan (dependencies / container images) + load/resource smoke test
4. release branch: Final image signing + version locking + release announcement

Multi-person Mode Checklist (Team Version)

• Requirements breakdown and create Issue
• Create feature-* branch and establish MR (draft/formal)
• Code review passed + CI green light
• Merge to development trigger DEV deployment
• Release candidate freeze and merge to master (QUAL)
• QUAL validation passed (automated + manual)
• Create release-x.y.z branch and tag deploy PROD
• Monitor and record release (update RELEASE.md)
• Sync necessary hotfixes to all trunk branches

Branch Naming Convention Recommendations

Typical Parallel Development Strategy

• Use short-lived feature branches (1–5 days).
• Avoid large comprehensive giant branches; break complex requirements into multiple feature branches serial or parallel.
• Regular (at least daily) sync development to local to avoid large conflicts.

Common Pitfalls and Avoidance

Recommended Tools/Strategies

• Pre-commit hooks: Formatting, static scanning (flake8 / black / isort etc.).
• Auto-generate CHANGELOG: Parse Conventional Commits.
• Version auto-increment script (optional): Calculate next version based on commit types.
• Protected branches: Prohibit direct push to master / release-*, must go through MR.

Multi-person mode emphasizes: Transparency (MR records) + Reviewable (Review) + Rollback capability (Tag + Release branch) + Stability (Multi-level Gates).