hinterland/documentation
2
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5ae28e020cfed59611ae80e276bdb7ae75f5fda1
documentation/CONTRIBUTING.md
T
yukkop 5ae28e020c docs: ~commit convention
2026-09-14 00:09:06 +00:00

7.5 KiB
Raw Blame History

Contribution conventions

Branch conventions

  • <type>/<subject>[/<subsubject>, ...]

<type>

This should be one of:

  • feature For work on a feature, look at feat commit type description for further info.
  • 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

Examples:

  • feature/note_preview - working on feature note_preview in src/feature/note_preview directory
  • feature/note_graph/note_graph_ui - working of submodule note_graph_ui of module note_graph in src/feature/note_graph directory
  • fix/configuration - fixing how configuration works (it was doing unwraps/expects, rewrite it to returning Results, which is breaking API change and technically crash fix so not refactor, and not a feature because nothing new was added)
  • feature/graph-trait - This is now the branch that added src/lib/graph.rs was named. At first i was thinking that it is hard to fit such a fundamental thing to the feature model, but it's not that fundamental.
    It's primarily a part of note_graph feature, and so ones like this should be named feature-first, not library-first.
    Most of the time if you adding something you add it for some feature. If most of your work in this branch is a library, for example a force-directed placement implementation or a environment variable substitution parser, it is still done first for some feature, specifically note_graph and accordingly configuration in that case.

<subject>

This 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

<subsubject>

This should be one of, in priority order:

  • feature/ submodule, like note_graph/note_graph_ui
  • meaningful short description or a naming for your scope, separated with dashes (-), one or a couple of words

Commit conventions

Pull requests

For pull request merges, use the default message, which is Merge pull request #N from <branch-name>

Merges

Don't use merges for your own local things. Use rebases.

Merge branch '<branch name>'

Follows default git merge message

TODO: maybe rebase all the history to be the above with some changes to it (it has to have the pull request number in it)

Default

This convention is based on Conventional Commits, but uses a local syntax for multiple types, scopes, and change markers.

The format is:

<message> ::= <clause>[; <clause>...]
<clause> ::= <type>[, <type>...][?][!]: [<scope>: ...] <subject>

[<body>]

[<footers>]

Including the empty lines

!

  • 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 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.
    • fix Commits, that fix a bug
    • refactor Commits, that rewrite/restructure your code, however does not change any behaviour
      • perf Commits are special refactor commits, that improve performance
    • style Commits, that do not affect the meaning (white-space, formatting, missing semi-colons, etc)
    • test Commits, that add missing tests or correcting existing tests
    • docs Commits, that affect documentation only
    • build Commits, that affect build components like build tool, dependencies, project version, ...
    • ci Commits, that affect the CI pipeline
    • chore Miscellaneous commits e.g. modifying .gitignore
    • revert Commits that revert other commits
  • 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>

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:

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

  • 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

<body>

  • Use the imperative, present tense: "change" not "changed", "add" not "added"
  • This is the place to mention issue identifiers and their relations

<footers>

List of format:

<subject>: <description>
  • BREAKING CHANGE: <description> Same as the !, but with description. Can't be included without the !.
  • Mention closed issues
    • Example: Closes: #1
  • Stuff like skip CI for tools like Github Actions

Examples

Single Type Commit

feat: configuration: +environment-variable support

Allow users to define configuration using environment variables.

Closes: #42

Multiple Types Commit

build, fix: deployment: ~Dockerfile, ~dependencies

- Fix a typo in the Dockerfile that causes build failures.
- Update dependencies to compatible versions.

Closes: #101

Breaking Unverified Commit

refactor?!: api: ~authentication method to OAuth2

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

Multiple Change Clauses

test: note_graph: note_graph_ui: +zoom tests; docs: note_graph: ~zoom documentation

- Add unit tests for note graph UI zoom controls.
- Update the README with zoom-control instructions.

Related: #303
Reference in New Issue View Git Blame Copy Permalink