kid-sid/claude-spellbook/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.

Author Checklist Before Requesting Review

• Self-review the diff in GitHub/GitLab before submitting — read your own code as if you were the reviewer.
• PR description is complete: What, Why, How, Testing.
• CI is green.
• No debug code, console.log, or commented-out blocks remain.
• No unresolved merge conflicts.

Release Tagging and Semantic Versioning

SemVer Rules

Format: MAJOR.MINOR.PATCH

Pre-release labels: 1.0.0-alpha.1, 2.3.0-rc.2 Build metadata (ignored in precedence): 1.0.0+20240102

Creating Annotated Tags

# Annotated tag — preferred for releases (stores tagger, date, message)
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3
 
# List tags
git tag -l "v*"
 
# Delete a mistaken tag (locally and remotely)
git tag -d v1.2.3
git push origin --delete v1.2.3

CHANGELOG

Maintain a CHANGELOG.md in Keep a Changelog format with sections Added, Changed, Deprecated, Removed, Fixed, Security.

## [1.2.3] - 2026-04-02
### Fixed
-Resolve null pointer in session validation (#456)
 
## [1.2.0] - 2026-03-15
### Added
-OAuth2 PKCE authentication flow (#399)

Automation Tools

Red Flags

• Long-lived feature branches (more than a week) — diverging from main for days accumulates merge conflicts and delays integration feedback; split the work into smaller increments or use feature flags
• Commit messages in past tense or with no type prefix — "Fixed the login bug" makes automated changelog generation and git bisect harder; use the imperative form with a Conventional Commits type: fix(auth): guard against null session token
• PR with 1,000+ LOC that mixes refactoring and feature work — reviewers cannot reason about two concerns simultaneously; split into a refactoring PR (no behavior change) and a feature PR on top
• Force-pushing to a shared branch — rewriting history that colleagues have already pulled causes divergent histories and lost commits; never force-push to main or a shared branch; use a new commit to amend
• Squash-merging without updating the PR description — the squash commit message defaults to the PR title only; the description (Why, How) is lost from git history where it would be most valuable for git log
• Merging without a required CI green check — bypassing status checks to "unblock" is the single most common source of regressions on main; enforce required status checks in branch protection settings
• Using lightweight tags for releases instead of annotated tags — lightweight tags have no author, date, or message; git tag -a v1.2.3 -m "..." is required for git describe and release tooling to work correctly
• No `CHANGELOG.md` entry on release — a tag with no changelog forces the next developer to read raw git log to understand what changed; automate with semantic-release or release-please

Checklist