Skip to content

Latest commit

 

History

History
190 lines (147 loc) · 7.25 KB

CONTRIBUTING.md

File metadata and controls

190 lines (147 loc) · 7.25 KB
Raw

Contributing

Thanks for contributing to the Qiskit Textbook! The general process is:

  1. Install the software
  2. Download a copy of the Textbook
  3. Make the changes you want to see
  4. Upload your changes and request to merge them into the Textbook (known as a pull request).
High-level illustration of the contributing workflow

0. Installation

You'll need some software installed to work on this repository (repo). We can install some packages for you automatically, but you must install the following packages manually. We recommend doing this first.

MacOS install instructions

We recommend installing Homebrew to manage your installations. You can think of Homebrew as an app store. This saves you from using each program's manual installer, and makes updating and uninstalling easier.

With Homebrew installed, you can open a terminal and run:

brew install python@3.8 git direnv vale

The only thing Homebrew can't install is GitHub Desktop, which we recommend to first-time contributors. Please go to the GitHub Desktop download page to install manually.

You may also want to hook direnv into your shell (see guide. Once complete, you can skip to the next step.

Software used:

  • Python 3.8: To run Qiskit and Jupyter notebook.
  • Git: To save and share your changes. If using Windows, choose to install Bash when asked by the installer.
  • Direnv: To automatically switch environments when in this directory.
  • GitHub Desktop or GitHub CLI: To easily work with github.com. If you're new to Git, we recommend the desktop application.
  • Vale linter: Used for one of the tests.

1. Fork & download the Textbook

1.1 Fork

For your first contribution, you'll need to fork the Textbook repository by clicking this link, this will take you to a new page. Click Create fork. This creates a copy of the repo, owned by your GitHub account.

1.2 Clone

Now, you can download (clone) your forked repository. For GitHub Desktop users, make sure you're looking at the web page for your fork (the url will be github.com/<your-user-name>/textbook, not github.com/Qiskit/textbook). Then click the green code button and choose Open with GitHub Desktop.

Then click clone. This will download the textbook repo to a folder on your computer. If you use GitHub Desktop, this folder will be at Documents/GitHub/textbook.

1.3 Setup

Next, install the specific packages we use in the Textbook and set up your environment. To set up automatically, first open a terminal in the repo folder.

ℹ️ GitHub Desktop users can do this through the app by going to Repository > Open in Terminal.

with your terminal in this folder, run:

./install.sh
What does this do?

If you're interested, this script will:

  • Setup a Python venv with the correct version of Python, and add a shell script to automatically switch to this venv when you move to this directory.
  • Set up your IPython & Jupyter config so that your notebook outputs match those already in the Textbook.
  • Set up Git commit hooks that lint the notebooks to adhere to our conventions (this helps with reviewing PRs and merge conflicts).

This may take a while. When it's finished, you'll see Qiskit Textbook setup complete!

2. Making changes to the Textbook

The source for each page in the Textbook is a Jupyter notebook, a file format that combines Python code, markdown, and rich content (e.g. images). To contribute to the Qiskit Textbook, you must edit these notebooks, then share your changes with us via GitHub.

2.1 Making a new branch

First, make a new branch named after the changes you plan on making (for example, fix-issue-544).

ℹ️ GitHub Desktop users can do this through the app. See Managing branches for more information.

2.2 Editing notebooks

Once on the appropriate branch, you can edit a notebook by navigating to this repo in a terminal and running

source .venv/bin/activate
python -m notebook

This will open Jupyter notebook, which you can use to make your changes. Check out this video if you're unfamiliar with notebooks.

The Qiskit Textbook also includes some extra features that we can't display in the notebook editor. We use a special syntax to tell the Textbook website where and how to insert these features. (TODO: include more about this).

2.3 Saving your changes

Once you've made your changes, you must save (commit) them using Git.

ℹ️ GitHub Desktop users: see Committing and reviewing changes to your project.

⚠️ If you get an error when comitting through GitHub Desktop, use the workaround below.

Workaround

We run some scripts on commit to search for common problems in notebooks, but sometimes GitHub Desktop can't find these scripts. To fix, you'll need to open the application from the textbook folder.

  1. Install the CLI tool (Go to the application menu and choose Install Command Line Tool),
  2. open a terminal in the repo (Repository > Open in Terminal),
  3. close GitHub Desktop,
  4. run the github command in the terminal,

then continue committing your changes.

3. Make a pull request

With your changes made and committed, you can now push these changes to GitHub, and ask us to consider incorporating them into the Textbook.

ℹ️ GitHub Desktop users: see Pushing changes to GitHub

After pushing your changes, switch back to the main branch before working on a different issue.

Testing

When you submit a pull request, we'll run some tests against your changes. You can read more about them in the tests folder.