commit-message

name: commit-message description: Guide for writing clear, consistent git commit messages following this repository's conventions compatibility: opencode metadata: domain: workflow scope: all-repos

Purpose

Use this skill when writing git commit messages. It enforces a formal Conventional Commits style suitable for open-source collaboration and future changelog generation, while still keeping messages aligned with this repository's tone.

Format

<type>: <subject>

• Default style: formal Conventional Commits (feat:, fix:, docs:, test:, chore:, etc.)
• No scope parentheses by default — this repo usually does not use type(scope): style; add a scope only if the user explicitly asks
• Subject: imperative mood, lowercase first word, no trailing period, max ~72 chars
• Body (optional): blank line after subject, wrap at 72 chars, explain why not what

Types

Notes:

• feat and fix are strongly preferred for code changes
• Use docs for skill files under .opencode/skills/
• Avoid legacy bare messages like updated, missing _extra_state, or add OV2 SP unless the user explicitly asks to preserve old repo style
• Revert and Merge are generated by git — don't manually write these types

Rules

1. Subject Line

• Imperative mood: "add", "fix", "refactor" — NOT "added", "fixes", "refactoring"
• Lowercase after type prefix: feat: add ... not feat: Add ...
• No period at the end
• Max 72 characters (hard limit for git log formatting)
• What changed, not how: fix: correct rotary_base override in 8B config not fix: changed value from 1000000 to 8000000

2. Body (when needed)

Use a body when:

• The change is non-obvious (e.g., subtle bug fix, architectural decision)
• There are constraints or caveats others should know
• The PR has multiple commits and each needs context

feat: add YaRN RoPE scaling to Megatron training path

Wire YarnRotaryEmbedding into QwenModel when --rope-type=yarn is set.
All default parameters match the official Qwen3-8B config.

Affected files:
- qwen_model.py: construct YarnRotaryEmbedding, return (emb, mscale) tuple
- attention.py: extract mscale before RoPE application
- arguments.py: add 7 CLI args for YaRN configuration

3. PR-linked Commits

When a commit will be part of a PR (most cases in this repo):

• The commit message should be self-contained — don't rely on PR description
• Reference issue numbers if applicable: fix: loading dataloader (#121)
• The (#N) suffix is added by GitHub on squash-merge — don't add it manually in local commits

4. Squash / Reword / Multi-author Rules

When cleaning up commit history before a PR:

• Prefer squashing small fixup commits by day: one coherent commit per day of work, unless a day contains clearly unrelated changes that should stay separate.
• If a squashed commit includes work from multiple authors, the final commit message must preserve every contributor with Co-authored-by trailers.
• Use each contributor's canonical Git name and email from the original commits.
• Rewording a commit message normally preserves the original Author; do not use --reset-author unless the user explicitly requests it.
• If the branch was already pushed, any squash/reword rewrites history and must be pushed with --force-with-lease, never plain --force.

Example multi-author squash commit:

docs: explain distributed offline packing workflow

Group one day of packing notes into a single guide so the PR history stays
reviewable while preserving each contributor from the original commits.

Co-authored-by: Alice Zhang <alice@example.com>
Co-authored-by: Bob Chen <bob@example.com>

5. Multi-file Changes

For commits touching many files, the subject should describe the intent, not list files:

# GOOD
feat: add YaRN RoPE support to QwenModel

# BAD
update qwen_model.py, attention.py, arguments.py, provider.py, config.py, model.py, mid_training.sh

6. What NOT to Write

• No generic messages: "update code", "fix bug", "misc changes"
• No WIP commits to main: "wip", "temp", "test" (use branches)
• No file lists as subject: "update foo.py and bar.py"
• No past tense: "fixed", "added", "updated" — use imperative
• No emoji unless the repo uses them (this repo does not)

Decision Tree

Is it a new capability?
  YES → feat: <what it enables>
  NO ↓

Is it a bug fix?
  YES → fix: <what was broken>
  NO ↓

Is it restructuring without behavior change?
  YES → refactor: <what was reorganized>
  NO ↓

Is it adding a new file/script/example?
  YES → docs: if documentation/skill, test: if test fixture, chore: if repo maintenance, feat: if user-visible capability
  NO ↓

Is it a config/dependency/version update?
  YES → build: for dependencies/build/Docker, ci: for CI, chore: for general maintenance
  NO ↓

Is it trivial (typo, comment, formatting)?
  YES → docs: for documentation typo, style: for formatting-only code changes
  NO → pick the closest type

Examples from This Repository

These are real commits — use them as reference for tone and length:

fix loading dataloader (#121)
missing _extra_state (#117)
Refactor model consistency checks and enhance encoder loading (#120)
add OV2 SP (#112)
update 30ba3b (#97)
feat: add MoE merge support for Qwen3-30B-A3B (#95)
refactor: move patch position block layout into task encoder (#89)
dev assert (#81)

Prefer the formal Conventional Commits shape for new local commits, even though older history contains mixed styles.

Better current-style examples:

feat: add packed SFT dataset assembly workflow
fix: prevent cross-sample attention leakage in packed runs
docs: explain cu_lengths attention boundaries
test: add HF/Megatron consistency checks for PP=2
chore: remove internal-only skill references
refactor: simplify Megatron checkpoint layout detection
build: update flash attention to v2.7.0

Quick Template

For most changes, just fill in:

<type>: <imperative verb> <what> [in/for/to <where>]

Examples:

• feat: add custom pipeline layer splitting for PP>2
• fix: correct rotary_base override for 8B config
• docs: document distributed offline packing workflow
• test: add OneVision2 consistency fixture for PP=2
• chore: remove internal-only skill references
• refactor: extract ViT encoder into standalone module
• build: update flash attention to v2.7.0