Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
156 lines (118 loc) · 6.24 KB

CONTRIBUTING.md

File metadata and controls

156 lines (118 loc) · 6.24 KB

How to contribute

We'd love to accept your patches and contributions to this project. We do have some guidelines to follow, covered in this document, but don't be concerned about getting everything right the first time! Create a pull request (discussed below) and we'll nudge you in the right direction.

Before you begin

Sign our Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; the CLA simply gives us permission to use and redistribute your contributions as part of the project. Please visit https://cla.developers.google.com/ to see your current agreements on file or to sign a new one. You generally only need to submit a Google CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Warning

Please note carefully clauses #5 and #7 in the CLA. Any code that you contribute to this project must be your original creation. Code generated by artificial intelligence tools does not qualify as your original creation.

Review our community guidelines

We have a code of conduct to make the ReCirq project an open and welcoming community environment. Please make sure to read and abide by the code of conduct.

Contribution process

All submissions, including submissions by project members, require review. We use the tools provided by GitHub for pull requests for this purpose. The preferred manner for submitting pull requests is to fork the ReCirq repository, create a git branch in this fork to do your work, and when ready, create a pull request from this branch to the ReCirq repository. The subsections below describe the process in more detail.

Please make sure to follow the Google Style Guides in your code, particularly the style guide for Python.

Repository forks

  1. Fork the ReCirq repository (you can use the Fork button in upper right corner of the repository page). Forking creates a new GitHub repo at the location https://github.com/USERNAME/ReCirq, where USERNAME is your GitHub user name.

  2. Clone (using git clone) or otherwise download your forked repository to your local computer, so that you have a local copy where you can do your development work using your preferred editor and development tools.

  3. Check out the main branch and create a new git branch from main:

    git checkout main -b YOUR_BRANCH_NAME

    where YOUR_BRANCH_NAME is the name of your new branch.

Development and testing

Before you begin developing ReCirq experiments and modules, we recommend you first create a virtual Python environment. You can use either Python's built-in venv module or another tool that you are comfortable with.

Then, in that virtual environment, install the ReCirq dependencies using pip:

pip install -r requirements.txt

You may need to install additional requirements, depending on the ReCirq experiment you want to work on. These additional requirements will be in a file named extra-requirements.txt in the experiment's subdirectory under recirq/. For example, if you were working with recirq/optimize, you would need to install its extra dependencies like this:

pip install -r recirq/optimize/extra-requirements.txt

Finally, if you are going to edit any of the Jupyter notebooks, install the additional requirements needed to run the notebook format checks:

pip install -r dev_tools/requirements/deps/tensorflow-docs.txt

Once the environment is set up, you can do your work and git commit your changes to your branch as needed.

To test notebooks for proper formatting and other issues, run the following command:

dev_tools/nbformat

To test your code, run

pytest recirq

Pull requests and code reviews

  1. If your local copy has drifted out of sync with the main branch of the ReCirq repo, you may need to merge the latest changes into your branch. To do this, first update your local main and then merge your local main into your branch:

    # Track the upstream repo (if your local repo hasn't):
git remote add upstream https://github.com/quantumlib/ReCirq.git

# Update your local copy.
git fetch upstream
git checkout main
git merge upstream/main
# Merge local main into your branch.
git checkout YOUR_BRANCH_NAME
git merge main

    If git reports conflicts during one or both of these merge processes, you may need to resolve the merge conflicts before continuing.

  2. Finally, push your changes to your fork of the ReCirq repo on GitHub:

    git push origin YOUR_BRANCH_NAME

  3. Now when you navigate to the ReCirq repository on GitHub (https://github.com/quantumlib/ReCirq), you should see the option to create a new pull request from your forked repository. Alternatively, you can create the pull request by navigating to the "Pull requests" tab near the top of the page, and selecting the appropriate branches.

  4. A reviewer from the ReCirq team will comment on your code and may ask for changes. You can perform the necessary changes locally, commit them to your branch as usual, and then push changes to your fork on GitHub following the same process as above. When you do that, GitHub will update the code in the pull request automatically.