126 lines
4.8 KiB
Markdown
126 lines
4.8 KiB
Markdown
# Contributing Guidelines
|
|
|
|
This document contains information and guidelines about contributing to this project.
|
|
Please read it before you start participating.
|
|
|
|
**Topics**
|
|
|
|
* [Asking Questions](#asking-questions)
|
|
* [Reporting Security Issues](#reporting-security-issues)
|
|
* [Reporting Non Security Issues](#reporting-other-issues)
|
|
* [Commit Messages](#commit-messages)
|
|
|
|
## Asking Questions
|
|
|
|
Questions are welcome! We encourage you to ask questions through GitHub issues.
|
|
Before doing so, please check that the project issues database doesn't already
|
|
include an answer to your question. Then open a new Issue and use the "Question"
|
|
label.
|
|
|
|
## Reporting Security Issues
|
|
|
|
If you have discovered an issue with this code that could present a security hazard or wish to discuss a sensitive issue with our security team, please contact us on [Telegram](https://hush.is/tg) or [Matrix](https://hush.is/matrix)
|
|
|
|
## Reporting Non Security Issues
|
|
|
|
A great way to contribute to the project
|
|
is to send a detailed issue when you encounter a problem.
|
|
We always appreciate a well-written, thorough bug report.
|
|
|
|
Check that the project issues database
|
|
doesn't already include that problem or suggestion before submitting an issue.
|
|
|
|
When reporting issues, please include the following:
|
|
|
|
* The Android API you're using
|
|
* The device you're targeting
|
|
* The full output of any stack trace or compiler error
|
|
* A code snippet that reproduces the described behavior, if applicable
|
|
* Any other details that would be useful in understanding the problem
|
|
|
|
This information will help us review and fix your issue faster.
|
|
|
|
## Code contributions
|
|
|
|
We **love** contributions!
|
|
|
|
All contributions _will_ be licensed under the GPLv3 license.
|
|
|
|
## Commit Messages
|
|
|
|
Commit history is an important part of the project's documentation.
|
|
Besides its obvious testimonial value, commits represent a point in time
|
|
in the project's lifetime in a given context. A good record of the changes that
|
|
occurred during the project's life helps to guarantee that it can outlive its
|
|
stakeholders no matter how foundational or crucial these individuals (or
|
|
groups) were. As any reading material, it is best appreciated and comprehended
|
|
when there's a visible structure that readers can follow and reason about.
|
|
|
|
For that we've defined a structure for commit messages that all contributors must
|
|
follow to maintain coherence on the project's commit log. The proposed format
|
|
has been inspired by [this great article](https://cbea.ms/git-commit/)
|
|
|
|
|
|
### Preparing to contribute to the project
|
|
The first thing you should look for is an existing issue. It is possible
|
|
that the contribution you are planning to work on was already discussed
|
|
by other users and/or contributors in the past. If not present, file an
|
|
issue following the criteria described in the preceeding sections.
|
|
|
|
Every contribution must reference an existing Issue. This issue is important
|
|
since it will be directly referenced in the title of your commit.
|
|
|
|
### Structuring a Commit
|
|
|
|
#### Commit Title
|
|
The first line of your commit message constitutes its _title_. Maintainers will
|
|
use commit titles to create release notes. Your contribution will be featured
|
|
in a public release of the project. Think of it as a newspaper headline. It
|
|
should be descriptive and provide the reader a broad idea of what the commit is
|
|
about. You can use a related github issue if it matches this criterion.
|
|
|
|
**Preferred title format**
|
|
|
|
`[#{issue_number}] {self_descriptive_title}`
|
|
|
|
Example
|
|
|
|
`[#258] - User can take the backup test successfully more than once`
|
|
|
|
optionally you can append the PR # between parenthesis.
|
|
|
|
#### Commit message's body
|
|
|
|
Use the body of the commit to bring more context to the change. Usually the bulk
|
|
of the problem might be explained in an issue. It's a good long term strategy
|
|
not to rely on such elements. If the project were to change its hosting, much of the
|
|
associated "Issues" and "pull requests" will be lost, yet the commit history will
|
|
probably be preserved and the context will also be.
|
|
|
|
If there are followup issues for this commit, consider referencing those as well.
|
|
|
|
|
|
### Example:
|
|
|
|
````
|
|
commit [some_hash]
|
|
Author: You <you@somedomain.io>
|
|
Date: some date
|
|
|
|
[#258] User can take the backup test successfully more than once (#282)
|
|
|
|
Closes #258
|
|
|
|
this checks that when the user taps the finished button on the phrase displayed it has definitely not passed the test before going to the recovery flow.
|
|
|
|
Note: this should actually go to the next or previous screen according to the context that takes the user to the phrase display screen from that context.
|
|
|
|
Add //TODO comment with the permanent fix for the problem
|
|
````
|
|
|
|
When you open a PR with a commit like this one the first line will land on the GUI's title field,
|
|
and the body will be added as the description of the PR.
|
|
|
|
Adding the text `Closes #{issue_number}` will tell GitHub to close the issue when the PR is merged.
|
|
|