Skip to content

Latest commit

 

History

History
314 lines (226 loc) · 12.1 KB

CONTRIBUTING.md

File metadata and controls

314 lines (226 loc) · 12.1 KB
Raw

CONTRIBUTING

Regardless if you are part of the core team or an external contributor, welcome and thank you for contributing to https://learn.qiskit.org!

In learn.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 learn.qiskit.org, you agree to abide by our code of conduct which we strongly recommend you read before continuing.

Following these guidelines shows you value the time and effort of the core contributors and maintainers of this site and so, thank you!

Table of contents

Start contributing

This repository is for developing and maintaining the Qiskit Textbook platform. If you want to contribute to Qiskit, the open-source Python library, you should go visit the Qiskit repository instead. Or if you want to contribute to the qiskit.org website, you should go visit the qiskit.org 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.

Before you start

Contributing to this repository, 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.

Opening issues

You can issues at https://github.com/Qiskit/platypus/issues/new for reporting a misfunction. Please do provide steps to reproduce and expected behaviour.

Core contributors classify the tasks according to its nature and prioritize them from sprint to sprint.

Contributing content

For anyone that wants to improve the content of the Qiskit Textbook, go to Qiskit/textbook. If you want to work on the website software, please head to the next section.

Adding new textbook versions

⚠️ This section is for maintainers

To add a new version to the textbook, add a release of the Qiskit/textbook repo under ./notebooks. Rename the Qiskit/textbook folder to a string beginning with v and followed only by digits and periods (e.g. v3.4)

Next, update the table of contents file by running:

python3 scripts/register_new_version.py <version-name>

If the version you've added is the new latest version (and should be the default content displayed) update LATEST_TEXTBOOK_VERSION in server/utilities.ts to your <version-name> string.

You should now be good to go.

Contributing code

Deciding what to work on

The core team's workload and backlog in managed via projects in qiskit.org

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.

Setup

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>/platypus.git
cd platypus
git remote add upstream https://github.com/Qiskit/platypus.git
git remote update upstream
git checkout main
git branch -u upstream/main
git pull

As 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.

Assigning yourself

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.

Working on an 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 pull upstream main
git checkout -b issue-1234-new-header

Now start adding your changes and remember to commit often:

git commit

And 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 main

Adding tests

Our team upholds the philosphy that a healthy codebase will include the proper amount of testing — in this project, we use Cypress 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

Pull requests serve a double purpose:

  1. Share the code with the team. So almost everybody is aware of how the code base is evolving.
  2. 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 GitHub

And 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 against a feature branch. In these occasions, remember to manually close the related pull requests after merging the pull request.

Live previews

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.

Code review

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.

Merging

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 style

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.

Type annotations

Regarding type checking, we aim at being compliant with TypeScript 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()

Final words

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.