From 5ae28e020cfed59611ae80e276bdb7ae75f5fda1 Mon Sep 17 00:00:00 2001 From: yukkop Date: Mon, 14 Sep 2026 00:09:06 +0000 Subject: [PATCH] docs: ~commit convention --- CONTRIBUTING.md | 96 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 71 insertions(+), 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b220f27..1c45cbb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ This should be one of: * `feature` For work on a feature, look at `feat` commit type description for further info. -* `fix` For fixing a but in a feature, look at `fix` commit type description +* `fix` For fixing a bug in a feature, look at `fix` commit type description * `refactor` Look at `refactor` commit type description * `hotfix` Temporary quick fixes of critical errors to master * `release` Pre-release finalization changes @@ -56,8 +56,6 @@ This should be one of, in priority order: For pull request merges, use the default message, which is `Merge pull request #N from ` -Follow - ### Merges **Don't use merges** for your own local things. **Use rebases**. @@ -70,11 +68,14 @@ TODO: maybe rebase all the history to be the above with some changes to it (it h ### Default -[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) +This convention is based on +[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), but +uses a local syntax for multiple types, scopes, and change markers. The format is: ``` -[()][!]: + ::= [; ...] + ::= [, ...][?][!]: [: ...] [] @@ -86,8 +87,15 @@ The format is: * This means that this commit introduces a breaking change. +### `?` + +* This means that the change has not passed testing or validation yet. +* Put it after all types and before `!` and `:`. +* `fix?: ...` is an unverified fix; `feat?!: ...` is an unverified breaking + feature. + ### `` -Specify one or more types, separated by commas, to reflect the nature of the changes. +Specify one or more types to reflect the nature of the changes. * **Allowed types**: * `feat` Commits, that adds a new feature or changes how the old feature works. Should only be user-presented features, changes to logic that does not affect what user of the app sees is `refactor`. @@ -101,24 +109,61 @@ Specify one or more types, separated by commas, to reflect the nature of the cha * `ci` Commits, that affect the CI pipeline * `chore` Miscellaneous commits e.g. modifying `.gitignore` * `revert` Commits that revert other commits -* **Myltiple Types**: - * When a commit involves multiple types, list them separated by commas within `{}` braces. +* **Multiple types**: + * When one change has multiple types, list them before the first `:`, + separated by commas: `feat, fix: ...`. + * Do not wrap types in `{}`. + +### `,` and `;` + +* Before the first `:`, a comma separates types that apply to the same change: + `build, fix: deployment: ~Dockerfile`. +* In a subject, a comma separates sibling change items that share the same + types and scope: `feat: web: +navigation, +search`. +* A semicolon separates independent change clauses. Each clause repeats its + own types, modifiers, and scope: + `fix: auth: ~token renewal; feat: admin: +session list`. ### `` -This should be one of, in priority order: +Scopes are optional context segments between the type and subject. Separate +them with `:`, without parentheses. Use one or more segments, from broad to +specific. + +A scope should be one of, in priority order: - `feature/` module name that you're currently working on - meaningful short description or a naming for your scope, separated with dashes (`-`), one or a couple of words #### **Examples**: -- (authentication) -- (feature/note_graph,note_graph_ui) -- (api,user-management) +- `feat: authentication: +OAuth2 support` +- ``feat: `note_graph`: `note_graph_ui`: +zoom controls`` +- `fix: api: user-management: ~permission check` + +Use backticks for exact code, package, service, command, or file identifiers +when that improves clarity: + +- ``feat: `proxydoe-bot`: control-panel: +pagination`` + +### Change markers + +Change markers concisely describe the operation performed on the affected +item: + +* `+item` The item was added, created, or enabled. +* `~item` The item was changed, updated, or reworked. +* `-item` The item was removed, deleted, or disabled. + +Markers are optional. Put a marker directly before the affected item, without +a space. The commit type explains the nature of the change; the marker explains +the operation. ### `` -* Use the imperative, present tense: "change" not "changed", "add" not "added" +* Without a change marker, use the imperative, present tense: "change" not + "changed", "add" not "added" +* After a change marker, use a concise name or noun phrase: `+runner`, + `~authentication flow`, `-legacy API` * Don't capitalize the first letter * No dot (.) at the end @@ -141,37 +186,38 @@ List of format: ## Examples ### Single Type Commit ```ignore -feat(configuration): add support for environment variables +feat: configuration: +environment-variable support -Allows users to define configuration using environment variables. +Allow users to define configuration using environment variables. Closes: #42 ``` ### Multiple Types Commit ```ignore -{build,fix}(deployment): fix Dockerfile and update dependencies +build, fix: deployment: ~Dockerfile, ~dependencies -- Fixed a typo in the Dockerfile causing build failures. -- Updated dependencies to the latest versions. +- Fix a typo in the Dockerfile that causes build failures. +- Update dependencies to compatible versions. Closes: #101 ``` -### Single Type Commit +### Breaking Unverified Commit ```ignore -refactor!(api): change authentication method to OAuth2 +refactor?!: api: ~authentication method to OAuth2 -Switched from basic authentication to OAuth2 for enhanced security. +Switch from basic authentication to OAuth2. This change has not passed the +integration test suite yet. BREAKING CHANGE: The authentication method has changed from basic auth to OAuth2. Clients must update their authentication mechanism. Closes: #202 ``` -### Single Type Commit +### Multiple Change Clauses ```ignore -{docs,test}(feature/note_graph,note_graph_ui): add tests and update documentation +test: note_graph: note_graph_ui: +zoom tests; docs: note_graph: ~zoom documentation -- Added unit tests for note graph UI components. -- Updated the README with new setup instructions. +- Add unit tests for note graph UI zoom controls. +- Update the README with zoom-control instructions. Related: #303 ```