Development Workflow

Development Workflow

A complete reference for Git branching, commit conventions, pull request workflow, code review practices, and release management — covering everything from first branch to published release.

When to Activate

• Starting work on a new feature, bug fix, or chore
• Writing a commit message
• Opening or reviewing a pull request
• Deciding on a branching strategy for a new project or team
• Creating a release or version tag
• Setting up commit message linting or changelog generation

Branching Strategies

Comparison Table

GitHub Flow

Developers branch from main, open a pull request, and merge back to main on approval. Merging to main triggers deployment. Suitable when every merged commit should ship.

git checkout -b feat/PROJ-42-add-oauth main
# ... commit work ...
git push -u origin feat/PROJ-42-add-oauth
# Open PR → review → merge → auto-deploy

Git Flow

Use when releases are batched on a schedule (e.g., sprint releases, versioned libraries).

# New feature
git checkout -b feature/PROJ-99-dark-mode develop

# Prepare a release
git checkout -b release/1.4.0 develop
# bump version, final fixes, then merge to main AND develop
git checkout main && git merge release/1.4.0
git tag -a v1.4.0 -m "Release v1.4.0"

# Emergency hotfix
git checkout -b hotfix/fix-login-crash main
# fix, then merge to main AND develop

Trunk-Based Development

All engineers commit to main (or merge very short-lived branches within a day or two). Unfinished work is hidden behind feature flags.

# Short-lived branch — merged same day or next
git checkout -b fix/null-check-cart
git commit -m "fix(cart): guard against null item list"
git push && gh pr create --fill

Decision Guide

• Deploy on every merge (CD pipeline) → GitHub Flow or Trunk-Based Development
• Scheduled release trains / versioned artifacts → Git Flow
• Maximum integration speed, mature CI, feature-flag infrastructure → Trunk-Based Development

Branch Naming

Pattern: <type>/<ticket>-<short-description>

Rules:

• Lowercase letters and hyphens only — no underscores or slashes in the description segment
• Include a ticket reference where one exists
• Keep total length under 50 characters
• No personal identifiers (no johns-branch)

Conventional Commits

Commit Type Reference

Breaking Changes

Add ! after the type to signal a breaking change, or add a BREAKING CHANGE: footer in the commit body.

feat!: remove legacy v1 authentication endpoint

BREAKING CHANGE: The /api/v1/auth endpoint has been removed.
Clients must migrate to /api/v2/auth before upgrading.

Scope

Optional. Place in parentheses between type and colon.

feat(auth): add refresh token rotation
fix(cart): prevent duplicate item insertion
chore(deps): upgrade eslint to v9

BAD / GOOD Example

# BAD — vague, no type, no scope, doesn't explain impact
git commit -m "fix stuff"

# GOOD — type, scope, imperative mood, explains what changed
git commit -m "fix(auth): resolve null pointer when session token is missing"

Pull Request Workflow

PR Description Template

## What
[one paragraph: what changed — be specific about files, components, or APIs affected]

## Why
[one paragraph: why this change is needed; link to ticket or issue]

## How
[optional: explain non-obvious implementation decisions or trade-offs]

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Tested manually: [describe steps and environment]

## Screenshots / Demo
[if UI change — include before/after screenshots or a short screen recording]

Draft PRs

Open as a draft (gh pr create --draft) when the branch is in progress and early feedback is wanted. Convert to ready-for-review once CI is green and the description is complete.

gh pr create --draft --title "feat(auth): add OAuth2 PKCE flow" --body "$(cat pr-body.md)"
gh pr ready <PR-number>   # convert to ready

Linking Issues

Closes #123      # closes the issue on merge
Fixes #456       # alias for Closes
Relates to #789  # reference without auto-closing

PR Size

Target under 400 LOC of production code per PR. Large changes should be split into stacked PRs where each PR builds on the previous and can be reviewed independently.

Merge Strategies

Pick one strategy per repository and enforce it consistently. GitHub allows disabling unwanted strategies under repository settings.

Code Review Practice

Reviewer Responsibilities

Reviewers check for: correctness, test coverage, security implications, performance concerns, naming clarity, and API design consistency. Checking formatting is the job of the linter, not the reviewer.

Feedback Labels

Prefix review comments to signal urgency and type:

Giving Feedback

• Be specific: reference the exact line or pattern, not a general feeling.
• Explain why: link to a doc, standard, or reason — not just "change this."
• Suggest an alternative: show what you'd prefer, don't just flag the problem.
• Don't be personal: comment on the code, not the author.

# BAD
This is wrong.

# GOOD
request: `userId` can be null here if the session has expired.
Suggest adding a null guard before the lookup:
`if (!userId) return res.status(401).json({ error: 'Unauthorized' });`

Receiving Feedback

• Separate ego from code — the review is about quality, not judgment.
• Ask for clarification before defending: "Can you say more about why X is preferred here?"
• Address every comment, even if just to acknowledge it: "Acknowledged — leaving as-is because [reason]."
• Avoid drive-by rewrites; if a comment sparks a bigger refactor, open a follow-up ticket.