hinterland/documentation
2
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: ~commit convention

Browse Source
This commit is contained in:
yukkop
2026-09-14 00:09:06 +00:00
parent 4ad7e6a95a
commit 5ae28e020c
1 changed files with 71 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+71 -25
View File
@@ -9,7 +9,7 @@
This should be one of: This should be one of:
* `feature` For work on a feature, look at `feat` commit type description for further info. * `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 * `refactor` Look at `refactor` commit type description
* `hotfix` Temporary quick fixes of critical errors to master * `hotfix` Temporary quick fixes of critical errors to master
* `release` Pre-release finalization changes * `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>` For pull request merges, use the default message, which is `Merge pull request #N from <branch-name>`
Follow
### Merges ### Merges
**Don't use merges** for your own local things. **Use rebases**. **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 ### 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: The format is:
``` ```
<type>[(<scope>)][!]: <subject> <message> ::= <clause>[; <clause>...]
<clause> ::= <type>[, <type>...][?][!]: [<scope>: ...] <subject>
[<body>] [<body>]
@@ -86,8 +87,15 @@ The format is:
* This means that this commit introduces a breaking change. * 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>` ### `<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**: * **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`. * `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 * `ci` Commits, that affect the CI pipeline
* `chore` Miscellaneous commits e.g. modifying `.gitignore` * `chore` Miscellaneous commits e.g. modifying `.gitignore`
* `revert` Commits that revert other commits * `revert` Commits that revert other commits
* **Myltiple Types**: * **Multiple types**:
* When a commit involves multiple types, list them separated by commas within `{}` braces. * 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>` ### `<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 - `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 - meaningful short description or a naming for your scope, separated with dashes (`-`), one or a couple of words
#### **Examples**: #### **Examples**:
- (authentication) - `feat: authentication: +OAuth2 support`
- (feature/note_graph,note_graph_ui) - ``feat: `note_graph`: `note_graph_ui`: +zoom controls``
- (api,user-management) - `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>` ### `<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 * Don't capitalize the first letter
* No dot (.) at the end * No dot (.) at the end
@@ -141,37 +186,38 @@ List of format:
## Examples ## Examples
### Single Type Commit ### Single Type Commit
```ignore ```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 Closes: #42
``` ```
### Multiple Types Commit ### Multiple Types Commit
```ignore ```ignore
{build,fix}(deployment): fix Dockerfile and update dependencies build, fix: deployment: ~Dockerfile, ~dependencies
- Fixed a typo in the Dockerfile causing build failures. - Fix a typo in the Dockerfile that causes build failures.
- Updated dependencies to the latest versions. - Update dependencies to compatible versions.
Closes: #101 Closes: #101
``` ```
### Single Type Commit ### Breaking Unverified Commit
```ignore ```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. BREAKING CHANGE: The authentication method has changed from basic auth to OAuth2. Clients must update their authentication mechanism.
Closes: #202 Closes: #202
``` ```
### Single Type Commit ### Multiple Change Clauses
```ignore ```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. - Add unit tests for note graph UI zoom controls.
- Updated the README with new setup instructions. - Update the README with zoom-control instructions.
Related: #303 Related: #303
``` ```