# Commit Conventions > AReaL commit message conventions. MUST load on every git commit -- provides Conventional Commits format with scope inference from file paths. - Skill: `areal-project/commit-conventions` (Agent Skill) - Install (CLI): `npx skillmds@latest add areal-project/commit-conventions` - Raw SKILL.md: https://api.skillmd.com/api/skills/areal-project/commit-conventions/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: areal-project (https://skillmd.com/u/areal-project) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/areal-project/commit-conventions --- # Commit Conventions Commit message conventions and scope inference rules for the AReaL repository. ## When to Use **ALWAYS load this skill when making any git commit in AReaL.** This includes: - Direct commits (`git commit`) - Commits during PR creation (`$create-pr` / `/create-pr`) - Commits delegated to sub-agents with this skill loaded - Any agent workflow that produces a commit ## Commit Message Format ``` (): [Optional sections:] Key changes: - change 1 - change 2 Refs: #123, #456 ``` ## Type Selection | Type | When to Use | | ---------- | -------------------------------- | | `feat` | New feature or capability | | `fix` | Bug fix | | `docs` | Documentation only | | `gov` | Governance or maintainer changes | | `style` | Formatting/style-only changes | | `refactor` | Code change without feature/fix | | `perf` | Performance improvement | | `test` | Adding or fixing tests | | `build` | Build system or dependencies | | `ci` | CI pipeline or workflow changes | | `chore` | Build, deps, config changes | | `revert` | Revert a previous commit | ## Scope Inference Infer scope from the **primary** changed file paths: | File Path Pattern | Scope | | ------------------------------------------------------------ | ------------------------------ | | `areal/workflow/` | `workflow` | | `areal/engine/` | `engine` | | `areal/reward/` | `reward` | | `areal/dataset/` | `dataset` | | `areal/api/` | `api` | | `areal/utils/` | `utils` | | `areal/infra/` | `infra` | | `areal/trainer/` | `trainer` | | `areal/models/` | `models` | | `areal/experimental/` | `experimental` | | `docs/` | `docs` | | `examples/` | `examples` | | `AGENTS.md`, `.agents/`, `.claude/`, `.codex/`, `.opencode/` | `agents` | | Multiple areas | Omit scope or use broader term | ## Rules - **Subject**: imperative mood, ~50-72 chars, no trailing period - **Body**: explain "why" not "what", wrap at 72 chars - **Key changes**: bullet list of main modifications (for complex commits with 3+ files) - **Refs**: reference issues/PRs if applicable ## Examples **Single file fix:** ``` fix(reward): handle empty completion in gsm8k Return 0 reward instead of raising exception when completion string is empty after extraction. ``` **Multi-file feature:** ``` feat(engine): add CPU offload support to ArchonEngine Enable torch_memory_saver for model offloading during rollout phase to reduce GPU memory pressure. Key changes: - Add offload/onload methods to ArchonEngine - Integrate with weight update flow - Handle ROCm compatibility ``` **Docs only:** ``` docs: update algorithm comparison table Add SAPO and GSPO to the algorithm family documentation with configuration examples. ``` **Agent/tooling changes:** ``` chore(agents): port review-pr command to OpenCode Add OpenCode-native commands with task() category delegation instead of hardcoded model names. Key changes: - Create .opencode/command/ with review-pr, create-pr - Replace hardcoded model routing with platform-native review routing - Add expert subagent consultation patterns ``` **Governance/maintainer changes:** ``` gov(agents): add maintainer ownership for service modules Update CODEOWNERS and maintainer references to reflect current governance responsibilities. Key changes: - Add maintainers for agent_service and infra ownership - Align governance docs with updated reviewer responsibilities ``` ______________________________________________________________________