finishing-a-development-branch

Finishing a Development Branch

When to Use

• After implementing a feature
• After all tests pass
• Ready to merge or create PR
• Cleaning up after development

When NOT to Use

• Work is still in progress and not all planned changes have been implemented
• Tests are failing and need to be fixed before the branch can be finalized
• Uncommitted changes remain that have not been staged or committed yet

---

The 5-Step Workflow

Step 1: Verify Tests

Run the project's test suite:

npm test
# or
pytest
# or
go test ./...

Decision point:

• Tests PASS → Continue to Step 2
• Tests FAIL → STOP. Cannot proceed with failing tests.

⚠️ STOP: Tests failing

Cannot proceed with merge/PR until tests pass.
Fix failing tests first, then restart this workflow.

Step 2: Determine Base Branch

Identify which branch this feature branch originated from:

# Check tracking branch
git branch -vv

# Or check common bases
git merge-base main feature-branch
git merge-base develop feature-branch

Common base branches:

• main or master - Production
• develop - Development
• release/* - Release branches

Step 3: Present Options

Offer exactly four choices:

## Branch Completion Options

Your feature branch `feature/email-verification` is ready.
All tests pass (42/42).

Choose how to proceed:

1. **Merge locally** - Merge into [base] on your machine
2. **Create Pull Request** - Push and open PR for review
3. **Keep as-is** - Leave branch for later work
4. **Discard** - Delete this branch and all changes

Enter your choice (1-4):

Step 4: Execute Choice

Option 1: Merge Locally

# Switch to base branch
git checkout main

# Pull latest
git pull origin main

# Merge feature branch
git merge feature/email-verification

# Verify tests still pass
npm test

# Delete feature branch
git branch -d feature/email-verification

Option 2: Create Pull Request

# Push branch to remote
git push -u origin feature/email-verification

# Create PR (using gh CLI)
gh pr create \
  --title "Add email verification" \
  --body "## Summary
- Implements email verification flow
- Adds verification token generation
- Includes tests for all scenarios

## Test Plan
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Manual testing complete"

Option 3: Keep As-Is

Branch preserved: feature/email-verification

Note: Remember to return to this branch later.
Current state: All tests passing, ready for merge.

Option 4: Discard

⚠️ WARNING: This will delete all work on this branch.

Type "discard" to confirm: _______

If confirmed:

# Switch away from branch
git checkout main

# Force delete branch
git branch -D feature/email-verification

# If pushed to remote, delete there too
git push origin --delete feature/email-verification

Step 5: Cleanup Worktree (if applicable)

For options 1, 2, and 4, cleanup the worktree environment:

# Remove worktree
git worktree remove ../feature-email-verification

# Or if worktree is in special location
git worktree remove /path/to/worktree

For option 3 (keep), preserve the worktree.

---

Decision Flow

┌─────────────────────────┐
│     Tests Passing?      │
└───────────┬─────────────┘
            │
       ┌────┴────┐
       │   NO    │──────► STOP: Fix tests first
       └─────────┘
            │
           YES
            │
            ▼
┌─────────────────────────┐
│   Present 4 Options     │
└───────────┬─────────────┘
            │
    ┌───────┼───────┬───────┐
    │       │       │       │
    ▼       ▼       ▼       ▼
 Merge    PR     Keep   Discard
    │       │       │       │
    ▼       ▼       │       ▼
 Cleanup Cleanup    │    Confirm
    │       │       │       │
    ▼       ▼       │       ▼
  Done    Done   Done   Cleanup
                          │
                          ▼
                        Done

---

Pull Request Template

When choosing Option 2:

## Summary

[Brief description of changes]

## Changes

- [Change 1]
- [Change 2]
- [Change 3]

## Test Plan

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing scenarios:
  - [ ] Scenario 1
  - [ ] Scenario 2

## Screenshots (if applicable)

[Add screenshots here]

## Related Issues

Closes #[issue number]

---

Verification Before Each Option

Before Merge

- [ ] Tests pass on feature branch
- [ ] Base branch is up to date
- [ ] No merge conflicts
- [ ] Tests pass after merge

Before PR

- [ ] Tests pass
- [ ] Branch pushed to remote
- [ ] PR description complete
- [ ] Reviewers assigned (if required)

Before Discard

- [ ] Confirmed with user (typed "discard")
- [ ] No valuable uncommitted changes
- [ ] Branch deleted locally
- [ ] Branch deleted from remote (if pushed)

---

Stack-Specific Pre-Merge Checklist

Python/FastAPI

pytest -v --cov=src                    # Full test suite
ruff check . && ruff format --check .  # Lint + format
mypy src/ --strict                     # Type check
pip-audit                              # Security audit
alembic upgrade head && alembic check  # Verify migrations

TypeScript/NestJS

npm test                               # Full test suite
npm run lint                           # Lint
npm run build                          # Build (catches type errors)
npm audit --production                 # Security audit
npx prisma migrate status              # Verify migrations

Next.js

npm test                               # Tests
next lint                              # Lint
next build                             # Build (catches SSR/RSC issues)

Stack-Specific PR Description Extras

Python/FastAPI PRs — include:

• Migration included? (alembic revision)
• New dependencies? (requirements.txt changes)
• Async patterns verified? (no blocking calls in async)

NestJS PRs — include:

• New modules registered in AppModule?
• DTOs have class-validator decorators?
• Prisma schema changed? (migration included)

Next.js PRs — include:

• Server vs Client components correct?
• Bundle size impact?
• 'use client' directives where needed?

---

Core Principle

"Verify tests → Present options → Execute choice → Clean up"

Never:

• Merge with failing tests
• Delete work without confirmation
• Skip the verification step
• Leave orphaned worktrees

---

Related Skills

• requesting-code-review - Use before finishing the branch to get review feedback, especially for Option 2 (Create PR)
• verification-before-completion - Run verification checks before claiming the branch is ready to finish
• executing-plans - If the branch was created from an execution plan, return to the plan to mark tasks complete