Git Workflow

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

Polling GitHub PR Checks

When waiting for GitHub checks to complete, use this inline pattern:

# Example: Poll a specific check with timeout
# Usage: Set PR, CHECK_NAME, TIMEOUT (seconds), and INTERVAL (seconds)
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 to poll:

• lint - Code style and TypeScript checks
• test-e2e - End-to-end tests
• test-jest - Unit tests
• sonarcloud - Code quality analysis
• Vercel - Deployment status