Skip to content

Latest commit

 

History

History
153 lines (99 loc) · 7.09 KB

CONTRIBUTING.md

File metadata and controls

153 lines (99 loc) · 7.09 KB
Raw

Contributing to mantra

Thank you for considering contributing to mantra, it means a lot to us!
Below are the most important topics to get you started.

Discussions

We use GitHub Discussions for exchanges with the community. It is a good place to start if you have any questions.

Issue/PR Labels

There are two labels to help possible contributors to get involved:

  • good-first-issue ... This label is used to mark issues that should be easy to implement without extensive understanding of the project
  • help-needed ... This label is used to mark issues, where project members need help to resolve it

For better asynchronous communication, we use the following labels:

  • waiting-on-assignee ... This label is used to indicate that the author or reviewer is awaiting response from the assignee
  • waiting-on-author ... This label is used to indicate that the assignee or reviewer is awaiting response from the author
  • waiting-on-reviewer ... This label is used to indicate that the assignee or author is awaiting response from the reviewer

To keep track of feature requests, we use the following labels:

  • declined ... This label is used to mark issues/PRs that they won't be considered/implemented further
  • req-missing-wiki-entry ... This label is used to mark [REQ] issues that there is not yet a related entry in the wiki
  • req-ready ... This label is used to mark [REQ] issues that they have enough information to be implemented

Wiki

We use the GitHub Wiki for developer related information. For example, it contains project requirements, decision records, and system views/models of the project.

Note: Issues for the wiki must be created in this repository, but PRs are handled in the GitHub repository of the wiki.

Development Setup

mantra is developed using Rust. See rustup on how to install the Rust tool chain.

GitHub workflows use a custom docker image that is automatically built on every push to main. You may install docker to build the image and test it locally using the Dockerfile at the root of the repository.

Pipeline:

Every contribution must pass the following steps.

  1. cargo fmt ... To get consistent code styling
  2. cargo clippy ... To get better code quality
  3. cargo build ... To make sure mantra still builds
  4. cargo test ... To ensure that all tests still pass

Please make sure that these steps pass before creating a pull request, to prevent unnecessary workflow runs.

Commit Message Convention

We have our own convention for git commit messages that are inspired by conventional commits.
This leads to more readable messages that are easy to follow when looking through the project's history. In addition, we use git commit messages to automatically get a change log using release-please from Google. As a result, commit messages not following our convention won't appear in the generated change log.

Note: We use squash merging for pull requests, so we are able to correct your commit messages, but please try to stick to the convention to make merging easier for us.

Commit Message Format

Each commit message consists of a header, a body, and a footer.
The header itself consists of a type and a subject:

<type>: <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Note: Any line of the commit message must not be longer than 72 characters, and the header should not be longer than 50 characters. This makes messages more readable on GitHub and in various git tools.

Type

The commit type must be one of the following:

  • feat ... Added a new feature
  • fix ... Fixed a bug of any kind
  • arch ... Neither adds features nor fixes bugs (e.g. renaming or restructuring)
  • chore ... Made other changes (should only be used for automatically generated commits)

Subject

The subject should contain a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize the first letter
  • do not add a dot . at the end

Note: It helps to write the subject in a way that continues the phrase This commit will ....

Breaking Changes

To mark a commit as breaking change, add an exclamation mark after the commit type, i.e. feat!: introduce some new feature. Another option would be to start the footer with BREAKING CHANGE: , but prefer to use the exclamation mark as it is directly visible in the project's history.

Body

The body should include the motivation for the change, and contrast this with previous behavior.

Note: Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes".

Footer

The footer may contain information about Breaking Changes, or reference GitHub issues that this commit Closes.

Note: The footer should be used rarely, because breaking changes should be marked by an exclamation mark, and issues should be closed by PRs.

Examples

feat: add support to parse headings

fix: fix parsing of headings

Heading levels were parsed incorrectly with an off-by-one error.

Hooks

We provide our own git hooks in the .hooks directory to help write commit messages according to our convention.

To use our commit-msg git hook, copy the commit-msg file into your .git/hooks/ directory. Alternatively set our .hooks directory as your global git hooks directory with the following shell command: git config core.hooksPath ./.hooks

Pull Requests

Create a pull request (PR) if you want to integrate your changes. In most cases you want to set main as the target branch.

The title of the PR must be written like a commit message. The section commit message convention above describes how these messages should be written.

Note: You must create a PR in the wiki repository if you want to make changes to the wiki.