Git Commit Conventions
Relevant source files
The following files were used as context for generating this wiki page:
Git commit messages in the mlx-qwen3-asr project are treated as a "self-contained unit of knowledge" and the "DNA of the change." The convention emphasizes maximum information density, providing future agents or engineers with enough context to reconstruct the reasoning, architectural constraints, and technical details of a change from first principles.
Sources: CLAUDE.md:155-163
Philosophy and Intent
The primary goal of these conventions is to create an institutional memory within the git history. Commit messages must avoid filler or boilerplate, focusing instead on the problem that triggered the work, rejected alternatives, and precise technical implementation details. This "generative kernel" approach ensures that even with zero prior context, the work remains reproducible and understandable.
Sources: CLAUDE.md:158-163
Commit Message Structure
The project enforces a specific multi-section structure for non-trivial changes to ensure high-density context.
The diagram shows the decision path between full and simplified commit formats based on the complexity of the change.
Sources: CLAUDE.md:166-193
Detailed Format Components
Required Sections for Full Format
For architectural decisions, new modules, or multi-file changes, the following sections are required:
| Section | Description |
|---|---|
| Summary | A concise, imperative mood description (e.g., feat: implement KV-cache streaming). |
| What Changed | A detailed breakdown of every file or module section modified. |
| Root Intent | The underlying problem, goal, or failure mode that motivated the work. |
| Seed Prompt | A high-context generative instruction allowing an engineer to reproduce the diff. |
| Files Changed | A summary including line counts for quick scanning. |
Sources: CLAUDE.md:166-189
Standard Commit Types
The project utilizes standard prefixes to categorize the nature of the change:
feat: New features or capabilities.fix: Bug fixes.refactor: Code changes that neither fix a bug nor add a feature.docs: Documentation only changes.test: Adding missing tests or correcting existing tests.chore: Changes to the build process or auxiliary tools.
Sources: CLAUDE.md:195
Automation and Integration
Commit data, specifically versioning and metadata, interacts with other repository systems. For example, scripts/update_readme_stats.py automatically refreshes README metadata based on the current state of the repository, including test counts and lines of source code. Furthermore, publishing scripts like scripts/publish_quantized.py use automated commit messages when uploading artifacts to external hubs like HuggingFace.
Sources: scripts/update_readme_stats.py:10-75, scripts/publish_quantized.py:96-101
Versioning and Release Workflow
The release process is tightly coupled with version control:
- Update version in
mlx_qwen3_asr/_version.py. - Execute quality gates (e.g.,
scripts/quality_gate.py). - Tag the commit with
v<VERSION>and push to the origin.
Sources: CLAUDE.md:223-230
Implementation Memory
The project maintains a "Continuous Learning" workflow that complements git history. While commit messages capture immediate technical rationale, long-term architectural decisions are documented in docs/memory/ and docs/DECISIONS.md.
The diagram illustrates the parallel tracks of technical documentation via Git and long-term implementation memory via documentation events.
Sources: CLAUDE.md:248-261, AGENTS.md:10-14
Summary
Git Commit Conventions in mlx-qwen3-asr serve as a technical DNA for the project. By requiring "Seed Prompts" and "Root Intent" descriptions, the project ensures that its history is not merely a list of changes, but a comprehensive knowledge base that supports both human developers and autonomous agents in maintaining and evolving the Metal-optimized ASR pipeline.
Sources: CLAUDE.md:155-163