Developer Reference

Version Control
& SDLC

A comprehensive reference covering every stage of the software delivery lifecycle — from planning and branching strategy through CI/CD, governance, and post-deployment monitoring.

14 Sections3 Interactive Features50+ Git Commands3 Branch Strategies

Section 01 · Planning & Issue Creation

Define work before touching code.

Every feature, fix, and experiment starts as a well-formed issue. Good issue hygiene is the highest-leverage investment a team can make — it eliminates ambiguity before it becomes rework.

Issue Types

◈

User Story

A feature expressed from the user's perspective. Drives product value.

As a

type of user

I want to

perform some action

So that

I achieve some goal

Acceptance Criteria

Given / When / Then

Story Points

1 / 2 / 3 / 5 / 8

Definition of Ready

Clear, unambiguous acceptance criteria in Given/When/Then format
Story points estimated by the team doing the work
All dependencies identified and unblocked
Designs or wireframes attached (if UI work)
No open questions that would block a developer from starting
Fits comfortably within a single sprint

Acceptance Criteria (BDD)

Givena logged-in user on the dashboard

Whenthey click 'Export to CSV'

Thena CSV file is downloaded containing all visible rows

Andthe filename includes today's date

Priority Levels

P0Critical

Production down or data loss. Fix immediately, all hands.

P1High

Core feature broken. Fix within current sprint.

P2Medium

Non-critical degradation. Next sprint or sooner.

P3Low

Nice-to-have improvement. Scheduled as capacity allows.

Sprint Planning Cycle

Day 1

Sprint Planning

Team commits to backlog items

Daily

Daily Standup

Sync on blockers + progress

Day 5

Mid-Sprint Review

Early demo, course-correct

Day 10

Sprint Review

Demo to stakeholders

Day 10

Retrospective

Improve the process

Section 02 · Repository Foundations

Structure the repo before the first commit.

Config files, branch protections, and lock files are not boilerplate — they are the skeleton of a healthy codebase. Getting them right on day one costs minutes; fixing them later costs weeks.

Init Workflow

Initialisegit init

→

Add Remotegit remote add origin <url>

→

First Commitgit add . && git commit -m 'init'

→

Pushgit push -u origin main

Key Config Files

Purpose

Tells Git which files and directories to never track — build artefacts, secrets, editor state, OS noise.

Example

# Dependencies
node_modules/
.pnp
.pnp.js

# Build outputs
dist/
.next/
out/

# Environment secrets
.env
.env.local
.env.*.local

# Editor
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

Branch Protection Rules

Require pull request before merging

No direct pushes to the protected branch. All changes go through a PR.

Require approvals (min. 1)

At least one reviewer must approve before a PR can be merged.

Dismiss stale reviews on new push

Approvals reset when new commits are pushed — reviewers must re-approve.

Require status checks to pass

CI must be green. Define which workflows are required.

Require linear history

Disallows merge commits. Forces squash or rebase merges for a clean graph.

Monorepo vs Polyrepo

Dimension	Monorepo	Polyrepo
Code sharing	Trivial — direct imports	Via published packages
Atomic changes	Single PR across projects	Coordinated multi-repo PRs
CI complexity	Affected-file detection needed	Simpler per-repo pipelines
Team autonomy	Shared tooling standards	Independent tech choices
Onboarding	One clone, everything works	Multi-repo mental overhead
Access control	Coarse-grained	Fine-grained per repo
Used by	Google, Meta, Vercel	Amazon, Netflix (historically)

Lock Files by Ecosystem

Node / npm

package-lock.json

via npm

Node / Yarn

yarn.lock

via yarn

Node / pnpm

pnpm-lock.yaml

via pnpm

Python

requirements.txt / Pipfile.lock

via pip / pipenv

Rust

Cargo.lock

via cargo

go.sum

via go mod

Section 03 · Branching Strategy

Branching is team choreography.

The branching model you choose dictates the pace and safety of your releases. There is no universal right answer — only the right fit for your team size, release cadence, and CI maturity.

Git Graph

GITFLOW

GITHUB FLOW

TRUNK-BASED

GitFlow

Strict, parallel-release model

Pros

+Clear separation of concerns

+Parallel hotfix + feature work

+Explicit release lifecycle

Cons

−Heavy process for small teams

−Long-lived branches → merge conflicts

−Overkill for continuous delivery

Best For

Software with versioned, scheduled releases (SaaS, libraries)

Branch Naming Conventions

Feature

feature/PROJ-123-add-oauth

Bug Fix

bugfix/PROJ-456-fix-null-pointer

Hotfix

hotfix/v2.1.1-payment-null-fix

Release

release/v2.2.0

Chore

chore/update-dependencies

Spike

spike/PROJ-789-evaluate-redis

Branch Lifecycle

Create

git checkout -b feature/X

→

Develop

git add . && git commit

→

Sync

git rebase origin/main

→

Review

Open Pull Request

→

Merge

Squash & merge

→

Delete

git branch -d feature/X

Section 04 · Local Development Workflow

Master the four-area model.

Git manages three local areas plus the remote. Most confusion about git commands dissolves once you understand which areas each command moves data between.

The Four-Area Model

Working Dir

→

Staging Area

→

Local Repo

→

Remote

git clone

Copies remote to local repo and working directory in one step

Select Command

Conventional Commits

TypeDescriptionExampleVersion Bump

feat✨A new featurefeat(auth): add OAuth2 login via GoogleMinor (1.x.0)

fix🐛A bug fixfix(cart): correct total calculation on discountPatch (1.0.x)

chore🔧Build process or toolingchore: update eslint to v9None

docs📝Documentation onlydocs(readme): add local setup instructionsNone

refactor♻️Code restructure, no behaviour changerefactor(api): extract pagination helperNone

test✅Add or fix teststest(user): add unit tests for validationNone

perf⚡Performance improvementperf(images): lazy-load below-fold assetsPatch (1.0.x)

Pre-Commit Hooks

ESLinteslint --fix

Catch JS/TS errors and enforce style rules before commit

Prettierprettier --write

Auto-format code — no more style debates in PRs

Secrets Detectiondetect-secrets scan

Prevent API keys and credentials entering the repo

Type Checktsc --noEmit

Fail on TypeScript type errors before they hit CI

Unit Testsvitest run --changed

Run tests for changed files only — fast feedback loop

git stash Flow

Stash

git stash push -m 'WIP: add auth'

Saves uncommitted work to a temporary stack

Switch

git checkout hotfix/urgent

Work on something else with a clean directory

Restore

git stash pop

Re-applies the most recent stash entry

Interactive Rebase Operations

pickKeep commit as-is

squashMeld into previous commit

rewordKeep commit, edit message

dropRemove commit from history

fixupSquash, discard commit message

$ git rebase -i HEAD~4

git bisect — Binary Search for Bugs

GOOD

TEST

BAD

Start

git bisect start

git bisect good v1.0

git bisect bad HEAD

Test Each Step

git bisect good

git bisect bad

Finish

Git identifies

the first bad

commit in O(log n)

Section 05 · Pushing & Remote Collaboration

Collaborate without breaking what others built.

Pushing code is a social act. Force-pushes, merge strategies, and conflict resolution patterns determine whether your team operates in flow or in fire-fighting mode.

Force Push: When and Never

Acceptable

✓Your personal feature branch — nobody else has checked it out

✓Cleaning up WIP commits before opening a PR (--force-with-lease is safer)

✓After interactive rebase on an unshared branch

✓Correcting a mistakenly committed secret on a brand-new branch

Never

✗main, develop, or any shared integration branch

✗Any branch that other developers have pulled or based work on

✗Production-tracking branches — rewrites deployment history

✗Without --force-with-lease (risks silently overwriting colleagues' pushes)

$ git push --force-with-lease origin feature/X

Safer: fails if remote has changed since your last fetch

Rebase vs Merge

Merge Commit

Creates a new merge commit that records the join point. History is non-linear but honest — it reflects what actually happened.

+Preserves full history — every branch is visible

+Non-destructive — no commit rewriting

+Merge commit shows when integration happened

−Can clutter history on high-frequency branches

$ git merge feature/auth

Conflict Resolution: Step by Step

1Fetch & Pull

git pull origin main

Download latest changes

→

2Conflict Detected

CONFLICT (content): Merge conflict in src/app.ts

Git marks conflicted files

→

3Open File

git diff --name-only --diff-filter=U

Identify all conflicted files

→

4Resolve

Edit file, choose HEAD or incoming

Keep yours, theirs, or both

→

5Commit

git add . && git commit

Mark conflicts resolved

Conflict Marker Format

<<<<<<< HEAD
const timeout = 5000;
=======
const timeout = 10000;
>>>>>>> feature/retry-logic

<<<<<<<Start of your current branch (HEAD)

=======Divider between the two versions

>>>>>>>End of incoming branch changes

Atomic Commit Principles

“One logical change per commit.” The unit of review is the commit, not the PR.

Revertability

One concern per commit means you can revert exactly the change that broke things — not unrelated code

Bisectability

git bisect works best when every commit is a consistent, buildable state

Review quality

Reviewers reason about one thing at a time — atomic commits reduce cognitive load

Changelog clarity

Conventional commits + atomic scope = automatic changelog that means something

Merge & Pull Request Process

How code moves from a feature branch into the shared trunk safely.

PR Lifecycle

Open: Ready for review. Reviewers can be requested.

PR Template Anatomy

CODEOWNERS Auto-Assignment

# .github/CODEOWNERS
# Global owners — review everything
*                   @team/platform

# Backend — Python services
/src/api/**         @backend-lead @srini

# Frontend — React components
/src/ui/**          @alice @bob

# Infrastructure
/infra/**           @team/devops

# Security-sensitive paths
/src/auth/**        @team/security

Review States

✓

ApprovedLGTM — ready to merge.

✗

Changes RequestedBlocking — must address before merge.

💬

CommentedNon-blocking feedback or questions.

Merge Strategies

Creates a merge commit that unites the two histories.

PROFull history preserved

CONHistory can become noisy

PR Size Guide

S< 50 lines

Ideal. Fast review, low risk.

M50–250 lines

Good. Single responsibility, reviewable in one sitting.

L250–500 lines

Acceptable. Consider splitting if possible.

XL500+ lines

Avoid. Approval rubber-stamping risk is high.

Code Review Process

How teams verify correctness, share knowledge, and maintain quality standards.

Reviewer Checklist — 8 Dimensions

Comment Types

🚫Blocking

"`user.password` is being logged on line 42 — this is a security incident waiting to happen."

💡Non-blocking

"nit: Could extract this into a `formatDate()` utility. Happy to merge as-is though."

❓Question

"Why are we calling `getUser()` twice here? I may be missing context."

🙌Praise

"Love how you handled the retry logic here — clean and robust."

Review SLA

PriDescriptionSLA

P0Security / Production incident fix< 1 hour

P1Breaking bug, blocking another team< 4 hours

P2Normal feature / bug PR1 business day

P3Docs, chore, low-risk refactor2 business days

Approval Workflow

Minimum 2 approvals required

CODEOWNERS must approve owned paths

Stale reviews dismissed on new push

Branch must be up to date before merge

Review Etiquette

✓ DO

✓Explain the why, not just the what

✓Suggest, don't dictate (use "consider" / "what if")

✓Acknowledge good decisions with praise

✓Separate blocking from non-blocking concerns clearly

✓Review the diff, not the person

✗ DON'T

✗Leave vague comments like "this is wrong"

✗Pile on blocking comments for style nits

✗Ghost a PR — respond even if just "looking at this tomorrow"

✗Approve without reading — rubber-stamping erodes trust

✗Request sweeping refactors unrelated to the PR scope

CI/CD Pipeline

Automated verification and delivery — the heartbeat of modern software teams.

Pipeline idle

name: CI/CD Pipeline

on:
  push:
    branches: ['**']
  pull_request:

jobs:
  pipeline:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run lint && npm run type-check
      - run: npm test -- --coverage
      - run: npm run test:integration
      - run: npm run build

      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ${{ env.IMAGE }}:${{ github.sha }}

      - uses: azure/k8s-deploy@v4
        with:
          manifests: k8s/
          strategy: rolling

Environment Promotion Flow

How a software build travels from laptop to production safely.

Environment Ladder

Click an environment rung to see details.

Blue-Green Deployment

Canary Release

Feature Flagnew-checkout-flow is OFF — all users see legacy checkout

Release Management

Versioning, tagging, changelog generation, and release ceremonies.

Semantic Version Calculator

major

minor

patch

v2.1.0

MAJOR

Breaking change — incompatible API change. Consumers must update.

MINOR

New feature — backwards-compatible addition. Safe to upgrade.

PATCH

Bug fix — backwards-compatible fix. Always safe to upgrade.

Git Tag Anatomy

git tag -a v2.1.0 -m "Release 2.1.0"

git tagGit tag command

-aAnnotated tag (stored as full Git object with tagger, date, message)

v2.1.0Version string — v prefix is convention, not enforced

-m "…"Tag message — describes the release. Appears in `git tag -v`

Release Candidates

Click to progress through the RC flow. Each RC gets deployed to staging and tested. Once all blockers are resolved, the final tag is cut.

Changelog from Conventional Commits

Raw commits (git log --oneline)

a1b2c3dfeat:add OAuth login via Google and GitHub

e4f5g6hfix:resolve null pointer in user.getRole()

i7j8k9lfeat!:redesign REST API — v2 endpoints

m1n2o3pdocs:update README with new setup steps

q4r5s6tfix:handle empty cart edge case at checkout

u7v8w9xperf:memoize expensive product catalog query

Hotfix Process

1.Branch off main (not develop)

2.Fix the bug in isolation

3.Merge to main + tag patch release

4.Cherry-pick or merge back to develop

Release Train Calendar (2-week sprints)

D10

D11

D12

D13

D14

Sprint start

Dev freeze

RC.1 cut

QA cycle

🚀 RELEASE

Sprint start

Retro

Post-Deployment

Deployment is the beginning, not the end. Observability, incident response, and continuous learning close the loop.

Monitoring Stack

◈APM

Application Performance Monitoring — traces, latency, throughput

Datadog APMNew RelicDynatraceOpenTelemetry

⚡Error Tracking

Real-time exception capture, stack traces, user context

SentryBugsnagRollbarHoneybadger

≡Log Aggregation

Centralised log storage, search, and alerting

ELK StackLoki + GrafanaSplunkDatadog Logs

◎Metrics

Time-series data, dashboards, threshold alerts

PrometheusGrafanaCloudWatchDatadog Metrics

Incident Response Flow

Detect0–2 min

Alert fires in PagerDuty / Slack. On-call engineer acknowledges.

▶ACK alert

▶Check dashboard

▶Assess severity (P1–P4)

SLA / SLO Dashboard

99.97%

Uptime (30d)

42ms

P50 Latency

187ms

P95 Latency

843ms

P99 Latency

0.03%

Error Rate

0.96

Apdex Score

A/B Test Result — Checkout Button Colour

Control (Blue)

3.2%

n = 12,400

Variant (Green)

3.9%

n = 12,350

Significance: 97.4%Lift +21.9%

Ship Variant B — statistically significant at p < 0.05

Feature Flag Cleanup Checklist

✓Remove flag evaluation code from all call sites

✓Delete the flag from LaunchDarkly / ConfigCat

✓Remove the corresponding database column / config key

✓Delete the old code path (the 'off' branch) entirely

✓Update changelog and notify stakeholders

Documentation & Knowledge

Code that isn't documented is an asset with an expiry date. The best docs live in the same repo as the code they describe.

Documentation Types

◈API Docs

OpenAPI / Swagger

Machine-readable API specification. Auto-generates SDKs, val…

◇ADRs

Architecture Decision Records

Immutable record of a significant architectural choice, the …

≡Runbooks

Operational How-Tos

Step-by-step operator guides for routine tasks, deployments,…

◎Wiki Pages

Team Knowledge Base

Searchable, collaborative long-form knowledge. Onboarding, p…

//Code Comments

Inline Documentation

JSDoc / docstrings explaining the 'why' not the 'what'. Auto…

⬡Diagrams-as-Code

Mermaid / PlantUML / D2

Version-controlled, diff-able architecture diagrams that liv…

◇ADR Template — Live ExampleADR-0012

▾

Diagram-as-Code (Mermaid)

gitGraph
   commit id: "init"
   branch feature/auth
   checkout feature/auth
   commit id: "add login"
   commit id: "add OAuth"
   checkout main
   branch hotfix/typo
   commit id: "fix typo"
   checkout main
   merge hotfix/typo
   merge feature/auth

Documentation Quality Checklist

◎All examples tested and runnable

◎Covers the most common error cases

◎Has a 'quick start' (< 5 min to first success)

◎Version-tagged and dated

◎Searchable (indexed in Confluence / Notion / Docs site)

◎Ownership clearly attributed

◎Updated as part of the same PR that changes the code

◎Reviewed by a developer who was NOT the author

New Team Member — Week 1 Checklist

Day 1

▶Dev environment setup guide

▶Repo access + SSH keys

▶Architecture overview doc

▶Meet the team

Day 2–3

▶First small PR (good-first-issue)

▶Code review process walkthrough

▶CI/CD pipeline tour

▶Codebase walkthrough with lead

Week 1

▶Own a small feature end-to-end

▶Runbook for at least one service

▶On-call shadow shift

▶30-day goals set with manager

Governance & Compliance

Git is your audit log. Every merge, every deploy, every config change is evidence — for your team and for your auditors.

Audit Trail

TimestampActorActionDetail

2024-03-15 09:12alice@co.com

PR #847 approved

feat: add payment gateway

2024-03-15 09:31ci-bot

Pipeline passed

build #1203 — all 847 tests green

2024-03-15 09:45bob@co.com

Deployed to prod

v2.14.0 → eu-west-1 (canary 5%)

2024-03-15 10:02bob@co.com

Canary promoted

5% → 100% — error rate stable

2024-03-15 14:20carol@co.com

Config changed

PAYMENT_TIMEOUT: 5s → 10s

2024-03-15 16:55alice@co.com

Tag created

v2.14.1 — hotfix: null check

Compliance Evidence Collection

CC6.1 — Logical access controls

✓Required 2 reviewers on main branch

CC7.2 — System monitoring

✓All merges logged with actor + timestamp

CC8.1 — Change management

✓No direct push to main; PRs mandatory

A1.2 — Availability monitoring

✓Deployment gate: staging tests must pass

Access Control Matrix

Developer

Lead

DevOps

Admin

Merge to main

✗

✓

✗

✓

Deploy to prod

✗

✓

Create release tag

✗

✓

Manage secrets

✗

✓

Add CODEOWNER

✗

✓

✗

✓

Delete branch

✓

⚿Signed Commits with GPG

▾

License Compliance

Scanning tools: FOSSABlack DuckTLDR LegalSnyk License

MITLow

Attribution only. Use freely in proprietary software.

Apache 2.0Low

Attribution + patent grant. Notice file required.

GPL v3High for SaaS

Derivative works must also be GPL. Copyleft.

LGPLMedium

Can link to LGPL library without GPL propagation.

AGPLVery High

Network use = distribution. Strongest copyleft.

BSD 2/3Low

Attribution. Non-endorsement clause (3-clause).

Team Communication & Notifications

The right signal to the right person at the right time. Too little: surprises. Too much: everyone ignores everything.

Integration Map

Notification Preferences Matrix

slack

dashboard

PR Opened

Review Requested

PR Merged

Pipeline Failed

Pipeline Passed

Deployed to Staging

Deployed to Prod

Alert Fired

Deployment Announcement Template

*🚀 Deployed to Production*  v2.15.0

*What shipped:*
• Payment gateway v2 (Stripe + Apple Pay)
• Checkout redesign — 22% fewer steps
• Fix: null pointer in order history (hotfix #847)

*Stats:*
Pipeline: ✅ 847 tests passed | Build: 2m 34s
Canary: 5% for 30min, no error rate change
Rollout: 100% of traffic as of 09:45 UTC

*Rollback:* `kubectl set image deploy/api api=app:v2.14.1`

*Links:* Runbook | Grafana | Sentry | Release Notes
*On-call:* @alice (primary) @bob (secondary)

On-Call Rotation

A

Alice

Mar 11–17

ACTIVE

B

Bob

Mar 18–24

C

Carol

Mar 25–31

D

Dave

Apr 1–7

Alert Fatigue Prevention

⏱Set minimum duration thresholds — alerts must fire for >5min before paging

◉Group related alerts into a single incident, not separate pages

◈Use severity tiers: P1 pages, P2 Slack, P3 dashboard-only

◎Review and tune alert thresholds monthly — aim for <2 false positives/week

✓Auto-resolve alerts when metrics recover; no manual ACK needed

Interactive Feature

Follow the Code

One feature. Eight milestones. From idea to production — every command, every artifact.

◉

Issue Created

Planning

1 / 8

A bug or feature is captured in the backlog with acceptance criteria and priority.

Key Commands

$ gh issue create --title 'Add Apple Pay to checkout'

$ gh issue view 847

Artifacts

◆JIRA ticket

◆Acceptance criteria

◆Priority label

Interactive Feature

Branch Strategy Comparison

Click any strategy to see the full branching rules, workflow, and commands.

GitFlow

Scheduled releases, complex branching

Branches5+ branch types

PR FrequencyLow — batched

Release CadenceScheduled (sprint / monthly)

solosmallmediumlargeenterprise

GitHub Flow

Simple, CI/CD-first, one rule

Branches2 branch types

PR FrequencyHigh — every feature

Release CadenceContinuous (every merge to main)

solosmallmediumlargeenterprise

Trunk-Based

Maximum velocity, feature flags, no branches

Branches1 branch (+ short-lived)

PR FrequencyContinuous (daily commits to trunk)

Release CadenceContinuous / on-demand

solosmallmediumlargeenterprise

Interactive Feature

Git Command Reference

59+ commands across 6 categories. Click any command for full syntax, options, and examples.

⌕

Setup8 commands

Basics10 commands

Branching9 commands

Remote10 commands

Undoing10 commands

Advanced12 commands

Version Control& SDLC

Define work before touching code.

Structure the repo before the first commit.

Branching is team choreography.

Master the four-area model.

Collaborate without breaking what others built.

Merge & Pull Request Process

PR Lifecycle

PR Template Anatomy

CODEOWNERS Auto-Assignment

Review States

Merge Strategies

PR Size Guide

Code Review Process

Reviewer Checklist — 8 Dimensions

Comment Types

Review SLA

Review Etiquette

CI/CD Pipeline

Environment Promotion Flow

Environment Ladder

Release Management

Semantic Version Calculator

Git Tag Anatomy

Release Candidates

Changelog from Conventional Commits

Hotfix Process

Release Train Calendar (2-week sprints)

Post-Deployment

Monitoring Stack

Incident Response Flow

Documentation & Knowledge

Documentation Types

Diagram-as-Code (Mermaid)

Governance & Compliance

Audit Trail

Compliance Evidence Collection

Access Control Matrix

License Compliance

Team Communication & Notifications

Integration Map

Notification Preferences Matrix

Follow the Code

Issue Created

Branch Strategy Comparison

GitFlow

GitHub Flow

Trunk-Based

Git Command Reference

Version Control
& SDLC