Modern Git Workflow on GitHub

Modern Git Workflow.md

Modern Git Workflow on GitHub

Based on: GitHub Flow + Conventional Commits + Squash Merge + Semantic Versioning

---

1. Core Philosophy

• One permanent branch: main
• All work in short-lived branches
• PRs are mandatory for all changes — no direct push to main
• Clean, linear history via Squash and Merge
• Branches deleted after merge
• Releases tagged from main

---

2. Branching Model

Naming Conventions

Prefix	Purpose	Commit Type
feature/	New functionality	feat
bugfix/	Fixing non-critical bugs	fix
hotfix/	Critical production fixes	fix
chore/	Maintenance (deps, config, cleanup)	chore
docs/	Documentation updates	docs
refactor/	Code restructuring, no behavior change	refactor
test/	Adding or updating tests	test
ci/	CI/CD pipeline changes	ci
perf/	Performance improvements	perf
build/	Build system changes	build
security/	Security-related fixes	security
release/	Release stabilization (temporary, optional)	—

Note: Branch prefixes (feature/, bugfix/) and commit types (feat, fix) are separate conventions. feature/ is the standard branch prefix in GitHub Flow; feat is the corresponding Conventional Commits type. Some teams prefer feat/ for consistency — either is valid as long as the team is consistent.

Branch Lifecycle

feature branch → push → PR → review → squash merge → main → delete branch

---

3. Repository Setup (Recommended)

Before the team starts, configure these on GitHub:

• ✔ Branch Protection Rule on main (block direct push)
• ✔ Required Reviewers (minimum 1 approval before merge)
• ✔ Required CI checks must pass before merge
• ✔ Auto-delete branches after merge
• ✔ PR Template (.github/PULL_REQUEST_TEMPLATE.md)
• ✔ CODEOWNERS (.github/CODEOWNERS) for automatic reviewer assignment

---

4. Pull Request Workflow

Steps

1. Create branch from main:

git checkout main && git pull
git checkout -b feature/login

2. Commit with Conventional Commits format:

git commit -m "feat: add login system"

3. Push branch:

git push -u origin feature/login

4. Open PR on GitHub

   • Use Draft PR for work-in-progress
   • Mark Ready for Review when complete

5. Code review + CI checks pass

6. Squash and Merge into main

7. Branch auto-deleted

---

5. Hotfix Workflow

For critical production bugs that cannot wait for the normal PR cycle.

main → hotfix/* → PR → squash merge → main → tag

Steps

1. Branch directly from main:

git checkout main && git pull
git checkout -b hotfix/fix-critical-crash

2. Apply the fix

3. Open PR to main (expedited review — minimum 1 reviewer)

4. Squash and Merge

5. Tag immediately on main:

git tag v1.4.3
git push origin v1.4.3

---

6. Release Workflow

Most modern teams release directly from main using tags. Release branches are optional — use them only when stabilization requires multiple coordinated fixes.

Option A: Tag from main ✔ Recommended

feature PR → squash merge → main → tag → release

git tag v1.2.0
git push origin v1.2.0

Option B: Release Branch (For Complex Stabilization)

main → release/v1.2.0 → final fixes → merge back to main → tag → delete

1. Create release branch from main:

git checkout -b release/v1.2.0

2. Apply only bugfixes — no new features

3. Merge back into main:

git checkout main
git merge release/v1.2.0
git push

4. Tag on main:

git tag v1.2.0
git push origin v1.2.0

5. Delete release branch:

git branch -d release/v1.2.0
git push origin --delete release/v1.2.0

release/* is temporary. It exists only for stabilization, then it is deleted.

---

7. Commit Message Convention (Conventional Commits)

Format

type(scope): description

Or without scope:

type: description

Rules

• ✔ lowercase
• ✔ imperative mood (add, fix, update)
• ✔ no period at end
• ❌ no uppercase types
• ❌ no full sentences

Commit Types

Type	Meaning
feat	New feature
fix	Bug fix
chore	Maintenance tasks
refactor	Code restructuring
docs	Documentation changes
test	Tests addition/update
ci	CI/CD changes
perf	Performance improvements
build	Build system changes
security	Security fixes

Examples

feat: add login system
fix: handle null response (#123)
chore: update dependencies
refactor: simplify auth flow
docs: update API documentation
feat(auth): add oauth login
fix(api): handle timeout error (#87)

Breaking Changes

feat!: redesign authentication API

BREAKING CHANGE: token format has changed from JWT to opaque token

---

8. Tagging & Versioning (SemVer)

Format

MAJOR.MINOR.PATCH

Rules

Change Type	Version Update	Example
fix	PATCH	1.4.2 → 1.4.3
feat	MINOR	1.4.2 → 1.5.0
Breaking change	MAJOR	1.4.2 → 2.0.0

Commands

git tag v1.2.0
git push origin v1.2.0

---

9. Changelog (Keep a Changelog)

Reference: keepachangelog.com

## [1.2.0] - 2026-06-12

### Added
- login system via OAuth

### Fixed
- crash on startup with empty config (#102)

### Security
- patched XSS vulnerability in input fields

---

10. Summary

feature branch
→ PR (review + CI)
→ squash merge → main
→ tag (vX.Y.Z)
→ delete branch
→ release

Practice	Recommendation
Branching model	GitHub Flow (one permanent branch: main)
Merge strategy	Squash and Merge
Commit format	Conventional Commits
Versioning	Semantic Versioning (SemVer)
Changelog	Keep a Changelog
Release	Tag from main (release branch optional)
Branch protection	Required on main
PR review	Minimum 1 required reviewer