Git Workflow

Git Workflow and Branching Strategy

NXTG-Forge uses trunk-based development: main stays always-deployable, work happens on short-lived feature branches, and changes land via squash-merged PRs. This SKILL.md is the lean operating guide; deep tables (commit/PR conventions, recovery recipes) live in the linked reference files.

Branch strategy

• main — always deployable, protected, requires PR + passing CI. Single source of truth.
• Feature branches — short-lived (1–3 days), single-purpose, named type/description: feat/user-authentication, fix/login-validation-bug, refactor/state-migration, docs/api-guide, chore/dep-bump.
• No long-lived branches — no develop, no release/*, no hotfix/*. Fix directly from main on a fix/* branch. (Reversing this needs an ADR.)

The core loop

# 1. Branch off fresh main
git checkout main && git pull origin main
git checkout -b feat/user-authentication

# 2. Work → stage EXPLICIT paths (never `git add -A` / `git add .`) → commit
git add src/auth/ tests/auth.test.mjs
git commit -m "feat: add JWT auth middleware"

# 3. Stay current — rebase, don't merge main in
git fetch origin && git rebase origin/main

# 4. Push (first push sets upstream)
git push -u origin feat/user-authentication      # later pushes: git push
git push --force-with-lease                        # ONLY after a rebase, never plain --force

# 5. Open PR
gh pr create --title "feat: add user authentication" --body "$(cat <<'EOF'
## Summary
- JWT-based authentication middleware + login/logout endpoints
## Test Plan
- [x] Unit tests for token validation
- [x] Integration test for the auth flow
EOF
)"

# 6. After approval + green CI
gh pr merge --squash --delete-branch

Stage explicit paths, not git add -A — it sweeps in unrelated dirty files and secrets. Rebase (not merge-from-main) keeps history linear. Push new work with -u; after a rebase that rewrote your branch, reconcile the remote with --force-with-lease (safe: it refuses if someone else pushed). See reference/commit-and-pr.md for the full commit-type list, PR template, size guidance, and merge-strategy trade-offs.