178 lines
5.7 KiB
Markdown
178 lines
5.7 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 but 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>`
|
|
|
|
Follow
|
|
|
|
### 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
|
|
|
|
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
|
|
|
|
The format is:
|
|
```
|
|
<type>[(<scope>)][!]: <subject>
|
|
|
|
[<body>]
|
|
|
|
[<footers>]
|
|
```
|
|
**Including the empty lines**
|
|
|
|
### `!`
|
|
|
|
* This means that this commit introduces a breaking change.
|
|
|
|
### `<type>`
|
|
Specify one or more types, separated by commas, 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
|
|
* **Myltiple Types**:
|
|
* When a commit involves multiple types, list them separated by commas within `{}` braces.
|
|
|
|
### `<scope>`
|
|
|
|
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
|
|
|
|
#### **Examples**:
|
|
- (authentication)
|
|
- (feature/note_graph,note_graph_ui)
|
|
- (api,user-management)
|
|
|
|
### `<subject>`
|
|
|
|
* Use the imperative, present tense: "change" not "changed", "add" not "added"
|
|
* 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): add support for environment variables
|
|
|
|
Allows users to define configuration using environment variables.
|
|
|
|
Closes: #42
|
|
```
|
|
### Multiple Types Commit
|
|
```ignore
|
|
{build,fix}(deployment): fix Dockerfile and update dependencies
|
|
|
|
- Fixed a typo in the Dockerfile causing build failures.
|
|
- Updated dependencies to the latest versions.
|
|
|
|
Closes: #101
|
|
```
|
|
### Single Type Commit
|
|
```ignore
|
|
refactor!(api): change authentication method to OAuth2
|
|
|
|
Switched from basic authentication to OAuth2 for enhanced security.
|
|
|
|
BREAKING CHANGE: The authentication method has changed from basic auth to OAuth2. Clients must update their authentication mechanism.
|
|
|
|
Closes: #202
|
|
```
|
|
### Single Type Commit
|
|
```ignore
|
|
{docs,test}(feature/note_graph,note_graph_ui): add tests and update documentation
|
|
|
|
- Added unit tests for note graph UI components.
|
|
- Updated the README with new setup instructions.
|
|
|
|
Related: #303
|
|
```
|