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