Contributing

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 they help us to build the thing right.

When communicating via code, READMEs, or any other written or visual communication, always apply our visual and written standards as described on our content guidelines which are a part of our brand guidelines.

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.

Three virtues

According to Larry Wall, the original author of the Perl programming language, there are three great virtues of a programmer:

1. Laziness: The quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don't have to answer so many questions about it.
2. Impatience: The anger you feel when the computer is being lazy. This makes you write programs that don't just react to your needs, but actually anticipate them. Or at least pretend to.
3. Hubris: The quality that makes you write (and maintain) programs that other people won't want to say bad things about.

Build the thing right

Make it:

• Performant: Fast, not slow.
• Available: Always up.
• Reliable: Never down.
• Scalable: Can get as big as we need, as we need it.
• Secure: No intruders.

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

More information about pull requests.

AI usage

Although we accept AI usage as part of our software development workflow, our AI policy requires a human-in-the-loop for peer reviews. This creates responsibilities for both the contributor and the reviewer.

For the contributor:

• You are ultimately responsible for the contents of a pull request.
  • As a corollary, you are responsible for bringing a pull request to a mergeable state. This is not the responsibility of the code reviewers.
  • You must manually review any code changes performed by an AI agent before pushing code up for review by other reviewers.
• You must demonstrate understanding and ownership of a pull request.
  • At the very minimum, the pull request title and description must be manually authored, and must provide rationale for the changes proposed.

For the reviewer:

You should be satisfied that the contributor has shown full understanding of a pull request. The following symptoms and behaviors might indicate otherwise:

• A fully AI-generated pull request title and description that don't provide a rationale for the proposed changes.
• Poor code quality or code that doesn't conform to the usual coding standards within a given project.
• "Meat-proxying" behavior when addressing pull request comments.

If any of the above are true, reply to the pull request with the following example text:

Suspected breach of contribution policy regarding AI usage (https://code.q-ctrl.com/contributing/)

You can then take one of the following actions:

• If you deem the offenses to be relatively minor, leave a Changes requested review with suggestions to improve the pull request.
• If you deem the pull request to be reviewable but in need of some rework, convert the pull request to a "draft".
• If you deem the entire pull request to be unreviewable and in need of reworking, close the pull request.

All the contribution guidelines outlined in this document continue to apply to AI-assisted pull requests.