git-workflow

name	git-workflow
description	Oak's git conventions including branch naming (feat/fix/chore prefixes), commit messages (conventional commits format), PR creation with templates, code review process, and CI check monitoring. Use when working with git, creating branches, committing code, or managing pull requests.

Git Workflow

Branch Naming

• Feature branches: feat/AI-XXXX-description or feat/description (prefer ticket ID when available)
• Bug fixes: fix/description
• Chores: chore/description (for project/config changes)
• Development: dev/description
• Testing: test/description
• Spikes: spike/description
• Refactoring: refactor/description

Commit Messages

• Format: type: description (conventional commits)
• Types: feat:, fix:, docs:, style:, refactor:, perf:, test:, build:, ci:, chore:, revert:
• Examples:
  • feat: add new lesson planner feature
  • fix: resolve authentication bug
  • docs: update API documentation

Quality Gates - How to Know Work is Correct

Before committing or creating a PR, verify all quality checks pass:

1. Format Check

pnpm prettier --write <changed-files>
# Or check all: pnpm prettier --check .

2. Lint Check

pnpm lint
# Or with auto-fix: pnpm lint:fix

3. Type Check

pnpm type-check
# Or: pnpm check

4. Tests

# Run all tests
pnpm test

# Run specific test
pnpm test -- -t "test name pattern"

# Run E2E tests (if relevant)
pnpm test-e2e

Pre-commit Notes

• For small fixes to the last commit, consider using amend
• Never skip hooks (--no-verify, --no-gpg-sign) unless explicitly requested

Pull Requests

• Template: Follow the PR template in .github/pull_request_template.md
• Formatting: All code must pass pnpm prettier --check . before submitting
• Reviewers: Ask before adding reviewers (team vs individual depends on context)
  • Team reviews: gh pr edit <PR-number> --add-reviewer oaknational/ai-devs
  • Individual reviews: gh pr edit <PR-number> --add-reviewer username

Checking PR CI Status

Use the check-prs script to monitor CI status across PRs:

# Check specific PRs
./scripts/check-prs.sh 940 941 942

# Check all your open PRs
./scripts/check-prs.sh

Polling a Specific Check

To wait for a specific check to complete:

PR=733; CHECK_NAME="lint"; TIMEOUT=120; INTERVAL=10; \
end=$(($(date +%s) + TIMEOUT)); \
echo "Polling PR #$PR for '$CHECK_NAME' (timeout: ${TIMEOUT}s)..."; \
while [ $(date +%s) -lt $end ]; do \
  check_status=$(gh pr checks "$PR" | grep "^$CHECK_NAME" | awk '{print $2}'); \
  echo "$(date '+%H:%M:%S') - $CHECK_NAME: ${check_status:-not found}"; \
  [ "$check_status" != "pending" ] && echo "✓ Completed: $check_status" && break; \
  sleep $INTERVAL; \
done || echo "⏱️ Timeout reached"

Common checks: lint, test-e2e, test-jest, sonarcloud, Vercel