Regardless if you are part of the core team or an external contributor, welcome and thank you for contributing to https://qiskit.org!
In qiskit.org, 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 qiskit.org, 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 https://qiskit.org, the website. If you want to contribute to Qiskit, the open-source Python library, you should go visit the Qiskit repository instead.
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.
Please, don't use this repository for asking questions about Qiskit: there are better ways to do it. Refer to our public Slack or post a question in stack overflow.
Contributing to qiskit.org, and other Qiskit repositories, 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 4 types of issues:
- Bug reports: for reporting a misfunction. Provide steps to reproduce and expected behaviour.
- Content issues: for noticing content-related problems such as typos or rewordings.
- Tasks: a general "to do", in case none of the other templates suits you.
- User stories: for identifying new value for the user.
In addition to these 4 templates, the most common types of tasks are:
- Plain tasks: these are the things that a core contributor usually work on during the sprint.
- Refactors: these aim at improving our codebase and reducing technical debt.
- Discussions: these provide a central hub for talking about something to reach a consensus.
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.
While the Qiskit community owns several projects in GitHub, we are asking for external contributors to please focus on the qiskit.org repository, for now.
To give our collaborators an idea of where the team needs help, we use the contributions welcome 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 qiskit.org 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.org.git
cd qiskit.org
git remote add upstream https://github.com/qiskit/qiskit.org.git
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.
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.
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 pull upstream main
git checkout -b issue-1234-new-headerNow start adding your changes and remember to commit often:
git commitAnd include a summary and some notes or clarifications if needed:
Create a new header layout.
Includes a new component factoring out the header of this new page and others.
From time to time, you want to check if your main branch is still up to
date. If not, you will need to merge
(or rebase),
then continue working:
git checkout main
git pull
git checkout issue-1234-new-header
git merge mainOur team upholds the philosphy that a healthy codebase will include the proper amount of testing — in this project, we use Jest as our UI testing tool of choice.
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-header
# 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. Unfortunately, this does not work when merging pull requests agains a feature branch. In these occassions, remember to manually close the related pull requests after merging the pull request.
As part of our continuous integration infrastructure, every pull request opened from the head repository that passes the build process, receives a dedicated deployment running on IBM Code Engine.
This allows the team to have live branch previews, making it easier to share
links and review changes as necessary. You can preview your working branch at
https://qiskit-org-pr-<pull-request-number>.<unique_id>.us-south.codeengine.appdomain.cloud/.
This means that for forked repositories the pull request will not generate a live preview and that step will be skipped.
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 solving 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.
We try to be compliant with Nuxt.js and Vue.js code conventions which are mostly enforced by
the Vetur extension of Visual Studio Code. We highly recommend installing the
Vetur extension when working
with Vue.js and to enable Vetur > Validation: Interpolation and Vetur > Validation: Template Props.
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 by running npm run lint. Notice that, although
some linting issues are reported as warnings, we don't allow any warning in our code base so
you will need to solve those problems or disable the linter for your contribution to pass the checks.
There are some linting issues that can be automatically fixed by running npm run fix-lint.
In the case you need to disable a rule, please provide an explanation supporting why the exception.
Regarding type checking, we aim at being compliant with
Tyepscript strict checks. That means, no implicit
any annotations, for instance although does not enforce any particular style in typing.
The golden rule is: declare your intentions and let type inference do the rest. Annotate function and method signatures, also class/object properties and module declarations, and rely on type inference for intermediate values.
Don't do:
function max(a, b) {
return a > b ? a : b;
}But instead:
function max(a: number, b: number): number {
return a > b ? a : b;
}When working with pure JavaScript objects, consider declaring an interface with the methods and properties you want, then implement a factory function returning an implementation of the interface.
Don't do:
export default {
scale: 2,
magnify(v) {
return v * this.scale;
},
};But instead:
interface MyType {
scale: number;
magnify(v: number): number;
}
function _factory(): MyType {
return {
scale: 2,
magnify(v) {
return v * this.scale;
},
};
}
export default _factory();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!
Now if you are a core contributor, perhaps you're interested in knowing more about our procedures in the Wiki.