docs: ~commit convention

2026-09-14 00:09:06 +00:00
1 changed files with 71 additions and 25 deletions
@@ -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 <branch-name>`

-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:
 ```
-<type>[(<scope>)][!]: <subject>
+<message> ::= <clause>[; <clause>...]
+<clause> ::= <type>[, <type>...][?][!]: [<scope>: ...] <subject>

 [<body>]

@@ -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.
+
 ### `<type>`
-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`.

 ### `<scope>`

-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.

 ### `<subject>`

-* 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
 ```