# Contribution conventions ## Branch conventions - `/[/, ...]` ### `` 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. ### `` 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 ### `` 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 ` ### Merges **Don't use merges** for your own local things. **Use rebases**. ``` Merge branch '' ``` *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: ``` ::= [; ...] ::= [, ...][?][!]: [: ...] [] [] ``` **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. ### `` 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`. ### `` 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. ### `` * 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 ### `` * Use the imperative, present tense: "change" not "changed", "add" not "added" * This is the place to mention issue identifiers and their relations ### `` List of format: ``` : ``` * `BREAKING CHANGE: ` 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 ```