Regardless if you are part of the core team or an external contributor, welcome and thank you for contributing to Qiskit Serverless!
In Qiskit Serverless, we aim at creating an excellent work-space where all of us can feel welcomed, useful, respected and valued. If you are thinking to contribute to this project, you agree to abide by our code of conduct which we strongly recommend you read before continuing.
Following these guidelines communicates you value the time and effort of the core contributors and maintainers of this site and so, thank you!
This repository is for developing and maintaining the Qiskit Serverless project.
There are many ways of contributing: from catching a typo to coming up with a way of improving performance or accessibility; you can open an issue, or you can prepare a patch. In any case, read the contribution guidelines for opening new issues and submitting pull requests.
Contributing to Qiskit Serverless assumes you have some level of Git knowledge. For external contributors, a basic understanding of repositories, remotes, branches and commits is needed. For core contributors, you should know about resolving conflicts and rebasing too.
There are tons of useful resources about Git out there.
You can open 3 types of issues:
- Bug reports: for reporting a misfunction. Provide steps to reproduce and expected behaviour.
- Enhancement request: to suggest improvements to the current code.
- Feature request: if you have a new use case or feature that we are not supporting.
Core contributors classify the tasks according to its nature and prioritize them from sprint to sprint. Types are not mutually exclusive and can change over time if needed.
Security vulnerabilities must be privately reported by following our Security Policy.
You'll need to install these tools on your development environment:
- python: the language qiskit-serverless is written in (Note that we currently support Python >=3.8,<3.11).
- git: for source control
- docker or podman: for building dev environment
- kubectl: for interacting with Kubernetes clusters
- helm: to install qiskit-serverless on Kubernetes
- tox: to run tests and build the documentation
Note: Installing the pip and venv python libraries will also be useful
To simplify the steps required to build and deploy qiskit-serverless, we recommend the use of virtual machines for runtime containers.
If you are on a Windows machine, it is recommended to use Windows Subsystem for Linux.
If you are on a Mac machine, it is recommended to use Colima to run docker and kubernetes container environments. It automatically installs containerd runtime and provides support for nerdctl, a CLI tool for containerd. Colima can be set up as follows:
brew install colima
brew install docker
colima start --cpu 4 --memory 8To check if colima is running:
colima statusTo list running containers:
nerdctl ps -aTo list container images:
nerdctl imagesTo give our collaborators an idea of where the team needs help, we use the help wanted label – this is appropriate for all contributors. In addition, for those who are relatively new to the open-source workflow or our codebase, feel free to view issues tagged with the good first issue label.
So you decided to get your hands dirty and start working on a patch? Then you need to know that the project follows the Forking Workflow with Feature Branches.
The above means we expect you to fork the project on your own GitHub account and make your main branch to
track this repository. A typical Git setup after
forking the project is:
# After forking the repository in GitHub
git clone https://github.com/<your_username>/qiskit-serverless.git
cd qiskit-serverless
git remote add upstream https://github.com/Qiskit/qiskit-serverless.git
git remote set-url --push upstream no_push
git remote update upstream
git checkout main
git branch -u upstream/main
git pullAs a core contributor due to some access limitations between forks and the head branch we encourage you to clone the repository instead of forking it.
This repository contains several projects with different technologies. Depending on the project that you selected (eg. gateway), from the project directory you will run:
pip install -r requirements.txt requirements-dev.txtfor python projects (strongly consider using a virtual environment!).helm dependency buildfor helm (Before running this command, make sure to check for helm configuration instructions specific to your selected project charts).terraform initfor terraform.
To set up a local development environment for the qiskit-serverless components (including the gateway, repository, ray nodes, etc.) using the latest changes you've made, use docker compose or podman-compose.
To build the images, run the following command from the root directory:
docker compose -f docker-compose-dev.yaml build
And to deploy your code, run the following command:
docker compose -f docker-compose-dev.yaml up
If you wish to rebuild only a specific component (for example, the gateway), you can do so as follows:
docker compose -f docker-compose-dev.yaml build gateway
The very first step to working on an issue is assigning yourself the issue. This gives all contributors the visibility into who is working on what.
In case you are not a contributor just participate in the issue that you are interested to help, and we will let you know the status of that issue.
When you are going to start working on an issue, make sure you are in your main
branch and that it is entirely up-to-date and create a new branch with a
meaningful name. The typical terminal code for this is:
git checkout main
git fetch upstream
git rebase upstream main
git checkout -b issue-1234-new-featureNow start adding your changes and remember to commit often:
git commitAnd include a summary and some notes or clarifications if needed:
Add a new feature.
The new feature will provide the possibility to do something awesome.
From time to time, you want to check if your main branch is still up-to-date. If not, you will need to
rebase
(or merge), then continue working:
git checkout main
git fetch upstream
git rebase upstream main
git checkout issue-1234-new-feature
git rebase main issue-1234-new-featureOur team upholds the philosophy that a healthy codebase will include the proper amount of testing.
From the project you are working on, you can run tests with tox -epy311.
Note if you run this command from qiskit-serverless top directory, it will build the project documentation.
For detailed testing guidelines using tox environments, please refer to this documentation.
As a part of the development backlog planning, we have internal discussions to determine which scenarios should be tested. For code that requires testing, please look for notes in the original issues, as we will do our best to provide ideal, meaningful cases to test.
If you feel that there's a test case that we have not considered, please comment in the original issue for the team to see.
Pull requests serve a double purpose:
- Share the code with the team. So almost everybody is aware of how the code base is evolving.
- Provide an opportunity for improving code quality.
When you think your work is done, push the branch to your repository:
git push origin issue-1234-new-feature
# Start a pull request in GitHubAnd
create a pull request
against main (or a feature branch).
When creating the pull request, provide a description and
link with the issue that is being solved.
Linking the issue has the advantage of automatically closing the related issue when the pull request is merged.
When you open a PR you will see a template in the pull request body. Please read it carefully and fill in the necessary information to help the code review process go smoothly.
Once you have sent a PR, the code contributors get notified, and there may be a code review. The code review helps to solve implementation, semantic and maintainability issues.
The repository also contains some automated checks such as tests and linting. For a pull request to be ready for merging it needs to pass automatic checks and have, at least, one positive review.
During code reviews, there are two prominent roles: the reviewer and the contributor. The reviewer acts as the keeper of best-practices and code quality, asking clarifying questions, highlighting implementation errors and recommending changes. We expect the contributor to take recommendations seriously and be willing to implement suggested changes or take some other action instead.
Notice we don't expect the contributors to address all the comments, nor the reviewer highlight all the issues, we hope both take some compromises to provide as much value and quality as it fits in the estimated effort.
We don't expect discussions to happen in the pull requests. If there is a disagreement, our recommendation is for the contributor to yield to the reviewer and for the reviewer to suggest other alternatives.
Once all automated checks are passing and there is a positive review, the pull request can be merged. If you are an external contributor, expect your PR to be merged by a core contributor.
Code in this repository should conform to PEP8 standards. Style/lint checks are run to validate this. Line length must be limited to no more than 88 characters.
Readability is what we value most. We expect reviewers to pay special attention on readability so at least they can understand new contributions to the codebase.
While developing, you can check linting issues. Notice that, although some linting issues are reported as warnings, we don't usually allow any warning in our code base, so you will need to solve those problems for your contribution to pass the checks.
In the case you need to disable a rule, please provide an explanation supporting why the exception.
This repository contains several projects and depending of the project you will need to run:
tox -elintfor python projects.helm lintfor the helm project.terraform validatefor the terraform project.
Thank you for reading until the end of the document! Abiding by these guidelines you express your willing in collaborating and contributing in a healthy way. Thanks for that too!