Commit Conventions
All commits in the Gerbtrace repository follow a consistent format. This page documents the conventions for commit messages, release notes, and hotfixes.
Commit types
Every commit subject starts with one of these prefixes:
| Prefix | When to use | Example |
|---|---|---|
Release vX.Y.Z | Version bump and tag commit | Release v1.2.0 |
hotfix: | Bug fix or patch pushed between releases | hotfix: fix BOM pricing for EUR currency |
feat: | New feature or significant enhancement | feat: add DXF export for panel outlines |
chore: | Housekeeping (dependencies, config, CI) | chore: sync package-lock.json |
ci: | CI/CD workflow changes | ci: add manual deploy trigger |
Subject line rules
- Maximum 72 characters.
- Use imperative mood: "fix crash" not "fixed crash" or "fixes crash".
- Lowercase after the prefix colon:
hotfix: fix BOM crash, nothotfix: Fix BOM crash. - No trailing period.
- Be specific:
hotfix: fix Elexess API crash on empty response, nothotfix: fix crash.
Body
- Separate from the subject with a blank line.
- Optional for hotfixes and chores. Recommended for features and releases.
- Wrap at 72 characters.
- Explain why, not what (the diff shows what).
Release commits
A release commit is created when bumping the version and tagging a new release.
Subject: Release vX.Y.Z (no extra text after the version number).
Body: The release notes content — the same flat bullet list that appears on the GitHub Releases page and in the desktop app's "What's New" dialog.
Example:
Release v1.1.0
- New modular viewer workflow with dedicated Files, PCB, Panel, Components, BOM, and Docs tabs
- BOM editing with focused details panel, inline field highlighting, and pricing visibility
- Team projects now support assignee selection with enforced access rules
Hotfix commits
A hotfix is any bug fix, patch, or correction pushed between releases. Hotfixes land directly on the release branch or on main after a release.
Subject: hotfix: <concise description of the fix>
Body: Optional. Include a 1-2 sentence explanation when the subject alone isn't self-explanatory.
Example:
hotfix: fix magic link redirect in Tauri desktop app
Switch Supabase client to implicit auth flow to prevent PKCE code-verifier
mismatches when magic links open in a different browser context.
Release notes
Release notes are written at the time the version tag is pushed. They appear in three places:
- The GitHub Releases page.
- The Tauri desktop updater (
latest.jsonbody field). - The in-app "What's New" dialog shown after a desktop auto-update.
Format
- Use a flat bullet list. No headings, no categories, no sub-lists.
- Each bullet is a single concise sentence describing one user-facing change.
- Focus on features and bug fixes that affect users. Omit internal refactors, CI changes, and dependency bumps unless they fix a visible problem.
- No emojis.
- No "What's Changed" heading or auto-generated contributor lists.
- For the initial release, start with "Initial release." before the bullets.
- Keep the text short enough to read comfortably in a small modal dialog.
Title
Use the bare version number: v1.2.0. Do not prefix with the product name.
Example
v1.1.1
- Complete in-app documentation hub with guides and references
- New Summary panel and file table preview for faster board review
- Improved PCB, BOM, and Pick and Place workflows
- Paste settings and project file import preferences now saved consistently
- Fix PCB field and viewer UI issues
Attribution
- Never include
Co-authored-bytrailers for AI tools (Cursor, CodeRabbit, Codex, or any other AI agent). - Never reference AI tools in commit messages, PR descriptions, or release notes.
- Human co-author trailers are allowed when explicitly provided.