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