F3 Nation Git Workflow

This workflow uses feature branches with merge commits to maintain clear history.

Branch Structure

• main - Production (merges from staging only)
• staging - Pre-production testing (merges from dev only)
• dev - Development integration (merges from feature branches)
• feat/*, fix/*, bug/* - Feature/fix branches (branch from dev)

Remotes

• md (High-Country-Dev) - Always push here
• f3 (F3-Nation client) - Push only when explicitly requested

Complete Workflow

1. Create Feature Branch

bash
1# Ensure dev is up to date
2git checkout dev
3git pull md dev
4
5# Create feature branch
6git checkout -b feat/your-feature-name

2. Make Changes and Commit

Make your changes, then commit with clear messages:

bash
1git add -A
2git commit -m "$(cat <<'EOF'
3Short description of changes
4
5- Detail 1
6- Detail 2
7EOF
8)"

3. Run CI Checks on Feature Branch

Before merging, run all CI checks on the feature branch:

bash
1# Run all checks (continues even if one fails, so you see all errors)
2pnpm run typecheck lint format test --continue

Or run individually:

bash
1pnpm typecheck  # Type checking
2pnpm lint       # Linting
3pnpm format     # Format checking
4pnpm test       # Tests (requires test database)

Fix any issues before proceeding to merge. If tests require the database:

bash
1pnpm reset-test-db
2pnpm test

4. Merge Feature into Dev

Use --no-ff to create a merge commit with two parents:

bash
1git checkout dev
2git merge feat/your-feature-name --no-ff -m "$(cat <<'EOF'
3Short description of changes
4
5- Detail 1
6- Detail 2
7EOF
8)"

5. Bump Version on Dev

Before merging to staging, bump the version:

Files to update:

• package.json (root)
• apps/map/package.json
• apps/api/package.json
• packages/shared/src/app/changelog.ts

bash
1# After updating files
2git add -A
3git commit -m "Bump to X.Y.Z"

Version bump types:

• Patch (3.6.1 → 3.6.2): Bug fixes, small improvements
• Minor (3.6.2 → 3.7.0): New features, larger changes
• Major (3.7.0 → 4.0.0): Breaking changes

6. Push Dev to Remote

bash
1# Normal push
2git push md dev
3
4# If history was rewritten (rebased/reset)
5git push md dev --force-with-lease

7. Merge Dev into Staging

Use --no-ff with a descriptive message (NOT "Merge branch 'dev'"):

bash
1git checkout staging
2git pull md staging
3git merge dev --no-ff -m "$(cat <<'EOF'
4X.Y.Z: Short description of changes
5
6- Detail 1
7- Detail 2
8EOF
9)"

8. Push Staging to Remote

bash
1# Normal push
2git push md staging
3
4# If history was rewritten
5git push md staging --force-with-lease

9. (Optional) Push to Client Remote

Only when explicitly requested:

bash
1git push f3 dev
2git push f3 staging

Quick Reference

Verify Merge Commit Parents

bash
1# Should show two parent commits
2git log --oneline --graph -5

View Branch Differences

bash
1# What's in dev but not staging
2git log staging..dev --oneline
3
4# What's in staging but not main
5git log main..staging --oneline

Reset Branch to Remote State

bash
1git checkout dev
2git reset --hard md/dev

Agent Instructions

When helping with this workflow:

1. Run CI checks on feature branch before merging (pnpm run typecheck lint format test --continue)
2. Always use --no-ff for merges to create merge commits
3. Never use generic merge messages like "Merge branch 'dev'" - always describe the changes
4. Bump version on dev before merging to staging
5. Include version in staging merge message (e.g., "3.6.2: Add feature X")
6. Push to md remote by default, only push to f3 when asked
7. Use --force-with-lease instead of --force when force pushing is needed

Example: Complete Feature Merge

bash
1# 1. Create feature branch and make changes
2git checkout dev && git pull md dev
3git checkout -b feat/my-feature
4# ... make changes ...
5git add -A && git commit -m "Add shared errors constants for role management"
6
7# 2. Run CI checks on feature branch
8pnpm run typecheck lint format test --continue
9
10# 3. Merge feature to dev
11git checkout dev
12git merge feat/my-feature --no-ff -m "Add shared errors constants for role management"
13
14# 4. Bump version
15# (edit package.json files and changelog.ts)
16git add -A
17git commit -m "Bump to 3.6.2"
18
19# 5. Push dev
20git push md dev
21
22# 6. Merge dev to staging
23git checkout staging && git pull md staging
24git merge dev --no-ff -m "3.6.2: Add shared errors constants for role management"
25
26# 7. Push staging
27git push md staging