Conventional @ t128n.dev

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.