Conventional
torben haack [t128n]
May 25, 2026
Conventional practices make project communication easier to read, search, automate, and review.
Conventional Commits
Conventional Commits define a structured commit message format.
Format
<type>[optional scope][optional !]: <description>
[optional body]
[optional footer(s)]
Examples
feat(search): support GitHub repository inputs
fix(package-json): show not-found message for missing package.json
refactor(api)!: remove legacy package lookup endpoint
BREAKING CHANGE: package lookup now requires a PURL-compatible input.
Reference
| Part | Meaning | Example |
|---|---|---|
type |
Kind of change | feat, fix, docs |
scope |
Area affected by the change | search, api, ui |
! |
Marks a breaking change | feat(api)!: |
description |
Short imperative summary | add package scanner |
body |
Optional explanation | Why the change was needed |
footer |
Optional metadata | Refs: #123 |
Common types
| Type | Use for |
|---|---|
feat |
New user-facing or API feature |
fix |
Bug fix |
docs |
Documentation only |
style |
Formatting, whitespace, lint-only changes |
refactor |
Code change without feature or bug fix |
perf |
Performance improvement |
test |
Tests only |
build |
Build system or dependency changes |
ci |
CI/CD configuration |
chore |
Maintenance work |
revert |
Reverting a previous change |
SemVer mapping
| Commit | Release impact |
|---|---|
fix: |
Patch |
feat: |
Minor |
! or BREAKING CHANGE: |
Major |
Conventional Branches
Conventional Branches define a structured branch naming format.
Format
<type>/<description>
Examples
feat/support-github-purl-inputs
fix/package-json-not-found-message
chore/update-dependencies
Reference
| Part | Meaning | Example |
|---|---|---|
type |
Kind of work | feat, fix, chore |
/ |
Separator between type and description | feat/search-input |
description |
Short kebab-case summary | support-github-purl-inputs |
Common branch types
| Type | Use for |
|---|---|
feat/ |
New feature |
fix/ |
Bug fix |
bugfix/ |
Bug fix, long form |
hotfix/ |
Urgent production fix |
release/ |
Release preparation |
chore/ |
Maintenance work |
Rules of thumb
- Use lowercase.
- Use kebab-case for readability.
- Keep names short but searchable.
- Include an issue number when useful.
Examples with issue numbers:
feat/69-support-purl-inputs
fix/70-package-json-error-state
chore/71-update-ci-cache
Conventional Comments
Conventional Comments define a structured format for review feedback.
Format
<label> [optional decorations]: <subject>
[optional discussion]
Examples
suggestion: Extract this parser into a small helper.
That would keep the route handler focused on request handling.
issue (blocking): This changes the fallback behavior for scoped npm packages.
Please add a regression test before merging.
nitpick (non-blocking): The variable name could be more specific.
Maybe `normalizedPackageInput` instead of `value`.
Reference
| Part | Meaning | Example |
|---|---|---|
label |
Type of feedback | suggestion, issue, nitpick |
decorations |
Extra context or priority | (blocking), (non-blocking) |
subject |
Main feedback | This can return null. |
discussion |
Optional reasoning or next step | Explanation, context, alternative |
Common labels
| Label | Use for |
|---|---|
praise |
Positive feedback |
nitpick |
Tiny preference, usually non-blocking |
suggestion |
Proposed improvement |
issue |
Concrete problem |
todo |
Small required follow-up |
question |
Clarification request |
thought |
Non-blocking idea |
chore |
Process task |
note |
Helpful context |
typo |
Spelling or wording issue |
polish |
Minor quality improvement |
quibble |
Very minor preference |
Common decorations
| Decoration | Meaning |
|---|---|
(blocking) |
Must be resolved before merge |
(non-blocking) |
Should not block merge |
(if-minor) |
Only fix if the change is small |
(security) |
Security-related concern |
(test) |
Test-related concern |
(ux) |
User-experience concern |
Traceable comments (Beyond Conventional Comments Spec)
Comments should optionally reference an issue or owner when the feedback should remain traceable.
Keep the main comment readable. Put issue references or ownership metadata at the bottom of the comment.
Format
<label> [optional decorations]: <subject>
[optional discussion]
[optional reference]
[optional owner]
Examples
issue (blocking): This changes the fallback behavior for missing package.json files.
The UI should distinguish “file not found” from “file found but invalid”.
Refs: #70
suggestion (non-blocking): Normalize GitHub repository URLs before routing.
That would keep `github.com/owner/repo` and `https://github.com/owner/repo` behavior consistent.
Refs: e18e/replacements.fyi#70
todo: Revisit the zero fallback once callers can distinguish unresolved data from zero values.
Owner: @serhalp
Refs: #123
Reference styles
| Format | Use for |
|---|---|
Refs: #123 |
Issue in the same repository |
Refs: owner/repo#123 |
Issue in another GitHub repository |
Refs: https://... |
External tracker, discussion, or non-GitHub issue |
Owner: @username |
Person with context or follow-up responsibility |
Prefer issue-bound references over user-bound references. Issues are more durable than people, usernames, or team assignments.
Discussion in the ATmosphere