The codebase is maintained using the "contributor workflow" where anyone can contribute patch proposals using pull requests.
To contribute a patch, the workflow is as follows:
- Fork the repository.
- Create a topic branch.
- Commit patches to the branch.
- Push changes to the fork.
- Create a pull request to merge the branch of the fork into this repository.
- If you had someone specifically in mind, ask them to review the pull request. Otherwise, just wait for a code review: most members with merge permissions receive notifications for newly created pull requests.
- Address review comments, if any.
- Merge and submit the pull request. If you don't have merge permissions, a reviewer will do it for you.
NOTE: Before starting any coding work, please make sure to discuss the issue first to agree on the optimal way of solving a particular problem. If no issue exists, create one unless the change is trivial, such as correcting typos and code formatting.
If you don't know where to start, look for issues labeled with good-first-issue.
In general, commits should be atomic and diffs should be easy to read. Please, do not mix style, formatting or moving code around with the actual code changes in the same commit. If a change is larger than 500 lines, consider creating multiple pull requests or multiple commits depending on how closely the patches are related to each other.
For example, if a change is much easier to do after a certain code reformatting, make the reformatting in a first commit and the actual change in the second. On the other hand, if a change includes multiple backend commits to create a new API endpoint as well as some UI modifications on the frontend, consider splitting backend and frontend into separate pull requests.
A commit message consists of a subject, the first line, and a body separated from the subject by a blank line.
The subject is conventionally formatted as "context: summary", fitting in 60 characters. The context is a short name of the primary spot in the codebase affected by the change. The summary is in imperative form so the line can be read as
This change modifies the _context_ to _summary_.
NOTE: That means the first line starts with lower case and does not end with a period.
The goal is that reading the commit message on any line using git blame
explains why the line exists.
For nontrivial changes, the subject alone is rarely self-explanatory. In this case, please add the body describing why this change is necessary, what it improves and how. Make sure the body lines fit in 72 characters, doesn't contain HTML, Markdown or any other markup language. Just plain text.
Try putting yourself in a reviewer's shoes and see whether they can, without prior knowledge of the issue, understand the why, the what and the how. Add any relevant benchmarks, performance and other information such as forums and mailing list discussions that helps in understanding and evaluating whether the change is the optimal way among alternatives.
If the change resolves an existing issue, bugfix or a feature implementation,
append to the body Fixes #123 or Closes #123 where #123 is the issue
number. If it's a partial resolution, use Updates #123 or Refs #123 instead.
Here's an example of a good commit message:
docs: add contribution guidelines
As the contributors list keeps growing, we really need to get on the
same page in how to propose and make changes to the codebase.
The guidelines in this commit align with what people with merge
permissions to this repo consider common practices.
There are other git repos, such as bitbox02-firmware, api-go and api-js.
We'll need the same guidelines in those, too. An alternative was to
publish a single copy on a website but having independent
self-sufficient repos was a prevailing benefit. So, will copy these
guidelines over to the other repos once this is committed.
Closes #96
See git log for more examples.
For details on working with git, please refer to the git manual.
A pull request contains one or more related git commits. Please, do not bundle independent and unrelated commits into a single pull request.
Just like a git commit message, a pull request consists of a subject and a body. If a pull request contains only one git commit, set its title and description to the commit's subject and the body. Otherwise, make an overall summary of what all the commits accomplish together, in a way similar to a commit message.
Before creating a pull request, please make sure all tests and lints pass locally on your machine. In a case where a pull request isn't ready for a regular code review and you're just looking for some early feedback, it's ok to let some tests fail but please mention it explicitly in the request description. See readme file in the root of the repository for setting up development environment and building/testing instructions.
At this stage one should expect comments and code reviews from other contributors. To address review comments, amend an existing commit with the new changes using
git commit --amend
and overwrite remote branch with
git push --force
See the following docs on creating github pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request