Q-CTRL logo

On this page

Contributing

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.

More information on creating an issue.

Submitting a pull request

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

  1. Fork and/or clone the repository.
  2. Follow the installation instructions in the README.
  3. Create a new branch.
  4. Make your changes.
  5. Push your changes and submit a pull request.
  6. Ensure a pull request title follows the Conventional Commits standard and uses one of the supported pull request types.
  7. Address any reviews.

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

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

After a pull request has been approved, if you squash merge it, its commit message to the master branch MUST follow the Conventional Commits standard. Since GitHub defaults a squashed commit message to a pull request title, a title MUST also follow that standard.

Note that:

  • We prefer squash merges from short-lived branches (for example feature/ABC-123) to long-lived branches (for example master).
  • If you’re a member of the Q-CTRL team, you’re responsible for merging your own pull requests once reviewed and approved.
  • The following table (whose two left columns are extracted from commitlint ) is a guide on how to choose a proper type for your pull requests/commit messages. The two columns on the right provide guidance on the type of release a commit triggers (major has precedence over minor, which has precendence over patch), and which section of the release notes each change should go in.

Supported pull request types

Type Purpose Type of release Release notes section
feat A new feature Minor Minor changes
fix A bug fix Patch Patch changes
perf A code change that improves performance Patch Patch changes
refactor A code change that neither fixes a bug nor adds a feature Patch (don’t add to release notes)
chore Other changes that don’t modify src or test files Patch (don’t add to release notes)
revert Reverts a previous commit Patch Patch changes
build Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) Patch Patch changes
ci Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) Patch (don’t add to release notes)
docs Documentation only changes Patch (don’t add to release notes)
style Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) Patch (don’t add to release notes)
test Adding missing tests or correcting existing tests Patch (don’t add to release notes)

More information about pull requests.