Guide to contributing to Q-CTRL projects

# Overview

This guide to contributing to Q-CTRL projects is intended for all contributors - from external open source developers, to outside collaborators and, of course, members of the @qctrl team.

When contributing to Q-CTRL projects, always bear in mind that Q-CTRL values the Three Virtues.

As a contributor, you agree to abide by the terms of the projects specific license and our code of conduct.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this section are to be interpreted as described in RFC 2119.

# Submitting an issue

To submit an issue against one of the Q-CTRL GitHub repositories:

  1. In the repository navigation, click “Issues”.
  2. Click “New issue”.
  3. Choose “Bug report” to create a report to help us improve or “Feature request” to suggest an idea for the project.
  4. Use the provided template to create your issue.

For more information on submitting issues, see the GitHub documentation.

# Submitting a pull request

To a submit a pull request to one of the Q-CTRL GitHub repositories:

  1. Fork and clone the repository.
  2. Configure and install any dependencies.
  3. Make sure the tests pass on your machine.
  4. Create a new branch.
  5. Make your change, add tests, and make sure the tests still pass.
  6. Push to your fork and submit a pull request.
  7. Pat yourself on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Follow the coding standards.
  • Write tests and make sure they all pass (for example pytest).
  • Lint your code using the file supplied in the project (for example pylint directoryname --rcfile=.pylintrc).
  • Keep your change as focused as possible (if there are multiple changes you would like to make that are not dependent upon each other, submit them as separate pull requests).
  • Write a good commit message.

Note that:

  • We prefer squash merges from short-lived branches (for example feature/ABC-123) to long-lived branches (for example master).
  • If a project has both development and master branches, we prefer the default merge commit option for merges between them.
  • When squashing commits, lines that add little meaning to the overall commit message (for example “Oops missed another instance”) should be removed.

# More information on pull requests

See the following resources for more information about pull requests: