Thank you for considering making a contribution to this repository. In this file, you will find guidelines for contributing efficiently. If you are unsure whether this is the appropriate repository for a particular issue, please review the repository structure of this organisation.
Please do not file an issue to ask a question. You will get faster results by using the resources below.
Before proceeding, please review our Code of Conduct.
This section describes the project's architecture. Please read it thoroughly before contributing to the project.
The project has been implemented in Python 3.8. Poetry is used for dependency management, allowing for a seamless installation of dependencies.
To set up your development environment, run the following command at the project’s root:
poetry installThe root folder contains the following folders:
- common. This contains the common logic of Immuni’s backend services. It is a Git repository—immuni-backend-common—used here as a Git submodule.
- docker. This contains the docker-compose configuration to seamlessly run the service, as shown in Environment.
- immuni_exposure_ingestion. This contains the logic of the specific backend service. tests. This contains the unit tests.
The immuni_exposure_ingestion folder is grouped by concerns. Specifically, as follows:
- apis. This contains the Sanic API endpoints, with one file per blueprint.
- core. This contains the service-specific configurations and the managers.
- helpers. This contains a collection of reusable utility methods.
- models. This contains the models (e.g., dataclasses, marshmallow, mongoengine) used by the backend service.
The backend service logic runs microservices, each one identified by a dedicated file within the immuni_exposure_ingestion folder. Specifically, as follows:
- sanic.py. This contains the sanic_app object, representing the Sanic API microservice.
- celery.py. This contains the celery_app object, representing the Celery distributed task management microservice.
To better understand how to run these microservices, see the dedicated commands in entrypoint.sh.
A script is provided to maintain consistent security and quality standards using the development tools described in the Technology Description's Backend Services Technologies section. This solution permits keeping the checks' configuration files in the common repository.
poetry run checks immuni_exposure_ingestionWhen a new pull request is opened, the CI checks for security, formatting, or linting issues. Please solve any before we can proceed with the review.
To preserve functionality after every change, please ensure that all existing test cases pass. You may be required to implement additional test cases, in the event that the existing ones do not ensure maximum coverage after your changes.
poetry run pytestWhen a new pull request is opened, the CI assesses whether all test cases pass and whether the maximum coverage is reached. Please solve any failures before we can proceed with the review.
This repository adopts the Gitflow branch management system.
When contributors wish to implement a new feature or a fix, they should branch from the development branch and open a pull request. Branches should have a meaningful name that adheres to the following convention:
<type>/name_of_feature_or_fix
The type prefix should be one of the following:
- feature. Used in the case that the branch implements a new feature.
- fix. Used in the case that the branch implements a fix.
Valid branch names are:
- feature/onboarding
- fix/paddings
Invalid branch names are:
- feat/onboarding
- fix_paddings
When the code is ready for a new release, a new release branch is cut from development. From the Gitflow website:
Once development has acquired enough features for a release (or a predetermined release date is approaching), you fork a release branch off from development. 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.
Please follow the Conventional Commits naming convention for consistency and to avoid problems with our continuous integration systems. The automatic systems also perform checks and mark as not ready for review any pull request that it determines has not followed the convention.
When you encounter a bug or an issue with the system represented in this repository, you may choose to let the developers know the nature of the issue.
The Immuni project is composed of different repositories—one for each component or service. If you wish to raise something strictly relevant to this repository (i.e., an Exposure Ingestion Service bug), please read on. However, to raise other issues or to highlight other bugs, please open an issue in the Documentation repository. This lets everyone involved see it, consider it, and participate in the discussion, without slowing down the overall process.
Before filing a new issue, please browse the relevant section and use the search functionality to check if it has already been filed by someone else.
- If this issue has previously been filed, please do not create a new one. Instead, add more information to the existing issue, or simply add the 👍 symbol to the first message. This helps the project maintainers to identify issues and prioritise accordingly.
- If the issue has not already been filed, please create a new one.
When creating a new issue, there are three categories:
- Bug report
- Feature request
- General issue
Please ensure that you select the appropriate category for the issue. Each one has a unique template designed to elicit the information required to reproduce and fix the issue. If the issue does not fall under Bug report or Feature request, please select General issue. With a general issue, it is especially important to provide a significant amount of detail, to help the project maintainers and any other collaborators understand the issue clearly.
When an issue is opened, a triage label is automatically assigned. The project maintainers are automatically notified of the issue's creation—they endeavour to address all issues as quickly as possible. When the issue has been triaged, a corresponding label will be assigned. Here is a list of all the possible labels.
If you are interested in contributing to Immuni but are unsure where to start, please search for issues with the Good first issue label. These issues are relatively easy tasks that can help you get familiar with the code.
After opening an issue, you may want to help the developers further. If the issue has been triaged and if the project maintainers give the green light, you may propose a solution. Doing so is always appreciated. For this, please use the Pull Request tool.
Before proceeding, please ensure that your proposal relates to an issue that has already been reviewed.
The first step in opening a pull request is to fork the project. Please log in to your account, then select Fork in the repository's landing page. This allows you to work on a dedicated fork and push your changes there. Then, if you wish to apply these changes back in the main Immuni repository, create a pull request targeting this repository. For more detailed information, please read this guide.
When creating a pull request, please choose a name that adheres to the Conventional Commits naming convention. It is important to review and follow this convention before creating a pull request. This ensures that the commit history remains clean and makes it easy to identify what each commit does.
After choosing the appropriate name, please use the following template for the body of the pull request:
<!--- 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. -->
## Description
<!--- Describe in detail the proposed mods -->
This PR tackles:
- ...
- ...
- ...
In particular, the ...
## Checklist
<!--- Please insert an 'x' after you complete each step -->
- [ ] I have followed the indications in the [CONTRIBUTING](../CONTRIBUTING.md).
- [ ] The documentation related to the proposed change has been updated accordingly (plus comments in code).
- [ ] I have written new tests for my core changes, as applicable.
- [ ] I have successfully run tests with my changes locally.
- [ ] It is ready for review! :rocket:
## Fixes
<!-- Please insert the issue numbers after the # symbol -->
- Fixes #ISSUE_NUMBERThere is a checklist indicating the different steps to follow. After completing each step, please mark it as such by inserting an X between the [ ]. When all the steps have been completed, the review process begins.
When a new pull request is opened, the CI performs some checks. These are as follows:
- Verification that the commits respect the repository's convention
- Verification that the source code is properly formatted
- Verification that the source code is properly linted
- Verification that the test cases are all successful
- Verification that the maximum code converge is reached
Pull requests that fall foul of these rules are not reviewed.
Labels are used to tag issues and make them more easily discoverable. Please refer to the Github website for more information.
| Name | Description |
|---|---|
| bug | Indicates an unexpected problem or unintended behaviour |
| documentation | Indicates that improvements or additions to the documentation are needed |
| 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 project maintainer wants help on an issue or a pull request |
| invalid | Indicates that an issue or a pull request is no longer relevant |
| question | Indicates that an issue or a pull request needs more information |
| wontfix | Indicates that work won't continue on an issue or a pull request |
| triage | Indicates that the issue still needs to be triaged |
| QA | Label coming directly from the QA department |