git-workflow
Oak 的 git 约定,包括分支命名(feat/fix/chore 前缀)、提交消息(常规提交格式)、使用模板创建 PR、代码审查过程和 CI 检查监控。使用 git、创建分支、提交代码或管理拉取请求时使用。
📖 中文导读:Oak 的 git 约定,包括分支命名(feat/fix/chore 前缀)、提交消息(常规提交格式)、使用模板创建 PR、代码审查过程和 CI 检查监控。使用 git、创建分支、提交代码或管理拉取请求时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
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-descriptionorfeat/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 featurefix: resolve authentication bugdocs: 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
- Team reviews:
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 checkstest-e2e- End-to-end teststest-jest- Unit testssonarcloud- Code quality analysisVercel- Deployment status