conventional-commits

# Conventional Commit Messages Follow these conventions when creating commits. ## Mindset You are writing for the next person who reads this commit log, not for yourself. Clarity and consistency matter more than brevity. Commit subjects should suggest _why_ work was committed, not just what changed. ## Prerequisites Before committing, ensure you're working on a feature branch, not the main branch. ```bash # Check current branch git branch --show-current ``` If you're on `main` or `master`, create a new branch first: ```bash # Create and switch to a new branch git checkout -b <username>/<type>-<description> ``` Name the branch with the `branch-naming` skill: `<username>/<type>-<description>[-swc-<issue>]`, where type matches the commit type (e.g., `janedoe/feat-add-user-auth`). Branches the Copilot app creates for its own sessions are exempt. ## Format ``` <type>(<scope>): <subject> <body> <footer> ``` The header is required. Scope is optional. All lines must stay under 100 characters. ## Commit Types Use the types allowed by `@commitlint/config-conventional`, which `commitlint.config.cjs` extends and the `commit-msg` hook enforces. | Type | Purpose | | ---------- | --------------------------------------------- | | `build` | Build system or CI changes | | `chore` | Routine maintenance tasks, dependency updates | | `ci` | Continuous integration configuration | | `docs` | Documentation changes | | `feat` | New feature | | `fix` | Bug fix | | `perf` | Performance improvement | | `refactor` | Code refactoring (no behavior change) | | `revert` | Revert a previous commit | | `style` | Code style and formatting | | `test` | Tests added, updated or improved | Source list: `@commitlint/config-conventional` (see `commitlint.config.cjs`). ## Subject Line Rules - Use imperative, present tense: "add feature" not "added feature" - **Always lowercase** — commitlint enforces lowercase subjects; sentence-case, start-case, and pascal-case are all rejected - No period at the end - Maximum 70 characters ## Body Guidelines - Explain **why** decisions were made, not how or what - Use imperative mood and present tense - Include motivation for the change - Contrast with previous behavior when relevant - Use a bullet point for each distinct concept or reason (this also handles line length naturally) - If a bullet's text exceeds 80 characters, continue on the next line flush with the bullet text (no indentation) ## Conventional Commits The commit contains the following structural elements, to communicate intent to the consumers of your library: - fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning). - feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning). - BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type. - types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others. - footers other than BREAKING CHANGE: {description} may be provided and follow a convention similar to git trailer format. ## Examples ### Simple fix (with line wrapping) ``` fix(api): handle null response in user endpoint - the user API could return null for deleted accounts, causing a crash in the dashboard - add a null check before accessing user properties to prevent the unhandled exception ``` ### Feature with scope (with bullet points) ``` feat(alerts): add Slack thread replies for alert updates - post a reply to the original Slack thread when an alert is updated or resolved instead of creating a new message - keeps related notifications grouped together for easier scanning - reduces noise in high-volume alert channels ``` ### Refactor ``` refactor: extract common validation logic to shared module - Move duplicate validation from three endpoints into a shared validator class - No behavior change ``` ### Breaking change ``` feat(api)!: remove deprecated v1 endpoints - Remove all v1 API endpoints deprecated in version 23.1 - Clients should migrate to v2 endpoints BREAKING CHANGE: v1 endpoints no longer available ``` ## Revert Format ``` revert: feat(api): add new endpoint - Reverts commit abc123def456 - Caused performance regression in production ``` ## Principles - Each commit should be a single, stable change - Commits should be independently reviewable - The repository should be in a working state after each commit ## References - [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)