224 lines
7.5 KiB
Markdown
224 lines
7.5 KiB
Markdown
# 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 `Result`s, 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](https://www.conventionalcommits.org/en/v1.0.0/), 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
|
|
```ignore
|
|
feat: configuration: +environment-variable support
|
|
|
|
Allow users to define configuration using environment variables.
|
|
|
|
Closes: #42
|
|
```
|
|
### Multiple Types Commit
|
|
```ignore
|
|
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
|
|
```ignore
|
|
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
|
|
```ignore
|
|
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
|
|
```
|