Thank you for considering to contribute to this repository! In the following file you will find instructions and guidelines for contributing efficiently. If you are unsure whether this is the exact repository for this particular issue, please review the repository structure of this organization.
⚠️ Please don't file an issue to ask a question! You'll get faster results by using the resources below.⚠️
Before proceeding further, please review our Code of Conduct.
The immuni project is formed by different repositories, one for each component / service. As such, if you want to report an issue (e.g., bug) strictly relevant to this repository please read on. However, if you want to propose a feature request, please open an issue in the documentation repo in order to let everyone involved in the project to spot it and be involved in the discussion. Refraining to do so and opening an issue/PR directly in this repo could slow down the overall process.
When you encounter a bug or an issue with the system represented in this specific repository you may decide to let the developers know what the issue is about.
⚠️ Please be aware that if you want to raise personal issues or talk about topics which are not relevant to the project, this is not the best place for doing so⚠️
- Browse the issue section and use the search functionality to look if the issue you encountered has already been filed.
- If this is the case, please avoid creating a new issue in order to avoid creating more entropy. Instead, you can add more info to such issue or, if the information are already present, you can insert the 👍 symbol in the first message. This will help the developers identify the relevant issues to be prioritized.
- If there is not a previous issue in the list, please proceed.
- Create a new issue.
-
While creating a new issue, you can see that there are three different possibilities:
- Bug report
- Feature request
- General issue
As such, please be careful to select the nature of the issue in order to be able to provide the relevant information to the maintainers of the project. In fact, for each one of the aforementioned categories, there is a different template containing sections that allow to provide detailed information to reproduce and, subsequently, provide a fix to the issue. If the issue does not fall in one of the first two categories it is possible to pick the third one but, if you do so, please provide a decent amount of detail in order to let other people clearly understand the issue.
When an issue is opened, a needs-triage label is automatically assigned. As
such, the maintainers will be notified of the creation event and they will try
to tackle it as soon as possible.
Therefor, when the issue has been triaged a corresponding label will be
assigned. Please see all the possible labels.
This repository adopts a branch management system that is heavily inspired by GitFlow. However, given that in Android and iOS Continuous Delivery can't be achieved, branches are used in a slightly different way.
The main branches are the following:
- master: the master branch contains the codebase that has managed to hit the production environment (that is, either Apple App Store or Google Play). Commits are manually merged in this branch by maintainers when a new build hits the production environment/
- development: the development branch is, as the name suggests, development happens. This branch serves as an integration branch for features and fixes. You can consider this branch as the unstable beta branch.
When contributors want to implement a new feature or a fix, they should branch from the
development branch and consequentially open a Pull Request. Branches should have a meaningful name. In particular, names should follow the convention
<type>/name_of_feature_or_fix. The type prefix should be one of the following:
- feature: in case the branch implements a new feature;
- fix: in case the branch implements a fix.
Some examples of valid branch names are feature/onboarding and fix/paddings, while invalid branch names are feat/onboarding or fix_paddings.
When the code is ready for a new release, a new release branch is cut from development.
Once
developmenthas acquired enough features for a release (or a predetermined release date is approaching), you fork a release branch off fromdevelopment. Creating this branch starts the next release cycle, so no new features can be added after this point—only bug fixes, documentation generation, and other release-oriented tasks should go in this branch.
During this stage, the focus is on preparing the release by fixing issues. It is not possible to add new features to the codebase.
Once Apple or Google approve the build, the release branch is merged in both development and master.
After opening an issue, you may want to further help the developers. If the issue has been triaged and there is endorsement from the maintainers, you may want to propose a solution for such an issue. That's great and always appreciated! 😄
As such, the tool you need to use for this use case is the Pull Request one.
⚠️ Please ensure that there is a pertinent issue related to what you are proposing and also make sure that someone has already reviewed it before proceeding further⚠️
The first step you need to do in order to correctly open a Pull Request is to Fork the project. As such, first of all you need to have an account on the GitHub platform and be logged in. Then, you have to select the Fork button in the landing page of the repository. This will allow you to work on a dedicated fork, push your changes over there and then, if you want to contribute back to upstream, you can create a Pull Request targeting this repository. For more extended information, please read this guide.
When creating a Pull Request, the first thing to do is to pick a name for the PR. The naming convention in place follows the Conventional Commits approach. As such, please carefully review such a specification before opening a PR in this specific repository. In fact, by following this convention we can ensure that the commit history will remain clean and it will be easy to easily spot what a commit does.
After picking the right name there is already a template in place for what concerns the body of the PR. The template is the following:
<!--- IMPORTANT: Please review [how to contribute](../CONTRIBUTING.md) before proceeding further. -->
<!--- IMPORTANT: If this is a Work in Progress PR, please mark it as such in GitHub. -->
<!--- Insert a title following the convention: [#ISSUE_NUMBER] where ISSUE_NUMBER is the number of the issue that this PR is going to solve. -->
## Description
<!--- Describe in details the proposed mods -->
As already mentioned in #ISSUE_NUMBER, this PR tackles:
* ...
* ...
* ...
In particular, the ...
## Checklist
<!--- Please insert and `x` when each of the following steps is done -->
- [ ] I followed the indications in the [CONTRIBUTING](../CONTRIBUTING.md)
- [ ] The documentation related to the proposed change has been updated accordingly (also comments in code).
- [ ] Have you written new tests for your core changes, as applicable?
- [ ] Have you successfully ran tests with your changes locally?
- [ ] Ready for review! :rocket:
## Fixes
<!-- Please insert the issue numbers after the # symbol -->
- Fixes #
Please review each line of such a template before proceeding in order to make sure that the project guidelines have been followed.
Also, there is a checklist indicating the different steps to be done. When each of the step is ready, please insert an x in between the [ ] to mark it as ready.
When all the steps will be ready the review process will start.
As already mentioned above, the naming convention in place is the Conventional Commits one. Please review the indications inserted there in order to be consistent and avoid problems with our Continuous Integration systems. In fact, the automatic systems will also perform this kind of checks and the PR will be marked as not ready for review if some of those checks will fail.
| Label name | Description |
|---|---|
| bug | Indicates an unexpected problem or unintended behavior |
| documentation | Indicates a need for improvements or additions to documentation |
| duplicate | Indicates similar issues or pull requests |
| enhancement | Indicates new feature requests |
| good first issue | Indicates a good issue for first-time contributors |
| help wanted | Indicates that a maintainer wants help on an issue or pull request |
| invalid | Indicates that an issue or pull request is no longer relevant |
| question | Indicates that an issue or pull request needs more information |
| wontfix | Indicates that work won't continue on an issue or pull request |
| need-triage | When the issue still needs to be triaged |
| backend | Issue dedicated to the backend side |
| frontend | Issue dedicated to the frontend side |
| QA | Label coming directly from the QA department |
In order to get involved with the community of developers please browse this page.