Contribute#

The goal of this document is to establish a common understanding among software contributors to D-Wave’s Ocean software projects based on the code conventions and best practices used at D-Wave.

If a project (repository) has its own contributing guide, it supplements this one and takes precedence where the two differ.

This document is intended to be a living document, and is not complete. Feedback is welcome.

Testing#

A feature or bugfix is complete only when the code has been unit-tested. Part of the pull-request process is to test your branch against the repository’s default branch (master or main, depending on the package), and so the more tests you provide, the easier the pull-request process.

A bugfix should come with a test that fails before the fix and passes after it.

Submitting Changes#

When contributing to a D-Wave project, fork the repository using the Github fork button and work in a feature branch in your own repository. In your feature branch, commit and push often, you can always rebase locally to edit your commit history and make it readable. To start a discussion, initiate a pull request. The sooner you start the pull request, the better. This allows early discussion on your feature and saves time and effort when you are ready to merge. When you are ready to merge, notify the repository owner and they will merge your code in.

Keep each pull request to one focused feature or fix. If the work grows beyond that, split it into separate pull requests.

Make the smallest change that solves the problem; don’t touch, refactor, or reformat unrelated code.

Follow the commit conventions described here:

TL;DR:

  • Separate subject from body with a blank line

  • Limit the subject line to 50 characters

  • Capitalize the subject line

  • Do not end the subject line with a period

  • Use the imperative mood in the subject line

  • Wrap the body at 72 characters

  • Use the body to explain what and why vs. how

If your branch is long-lived, rebase off of master periodically.

If you’re already familiar with Git, but rebasing is still scary, try this think like a Git guide.

Each commit should make sense in isolation; group semantically related changes together. If you need to amend changes you have already committed (for example, to fix a bug you discovered), and the pull request is not yet under review, use an interactive rebase (git rebase -i master) to fixup, squash, or edit the affected commits.

Once the pull request is under active review, don’t rewrite its history. Address reviewer comments in new commits, so that reviewers can see what changed since their last pass. Rebasing onto master to resolve conflicts is the exception; say so in a comment when you do it.

The master branch in a dwavesystems repository reflects the bleeding-edge developments of the project. Significant old versions forked from master are kept in version branches. For example, we might keep version branches 2.x and 3.x while master tracks the latest 4.x version. We try to minimize the number of version branches kept alive/maintained.

Stable releases are tracked using tags. These tagged snapshots are deployed to PyPI after successfully passing the test cases during continuous integration.

Release Notes#

Ocean packages use reno to manage release notes. When making a contribution that affects users (new features, behavior changes, bug fixes, deprecations, upgrade notes), create a release note by running

reno new your-short-descriptor-here

then edit the file created under releasenotes/notes/, remove the sections not relevant to your change, and commit it along with your changes. Changes with no user-visible effect (tests, CI, docs, internal refactoring) generally do not need a release note. See reno’s user guide for details.

AI-Assisted Contributions#

You may use automated tools such as AI coding assistants while contributing to Ocean as long as you use them responsibly.

Disclose their use in the pull request description, under the “AI Generation Disclosure” section of the pull request template: name the tool and model (and effort setting, if any), for example claude fable 5.1 (xhigh), describe how they were used, and identify which code or text is AI-generated. If you used more than one tool or model, say which parts each was responsible for. If none were used, write “No AI tools used”.

Review and understand everything you submit; do not use AI to speak for you in issues, reviews, or discussion (except for translation or grammar editing). See Ocean’s AI Policy for details.

Coding Conventions#

  • Variable naming should follow the well-known conventions of a language. Avoid uninformative or needlessly terse variable names.

  • Code is read more often than written.

  • Functions should do one thing.

  • Early pull requests and code reviews.

  • Early architecting/design. Code reviews can happen before any code has been written.

  • Use a consistent character limit of 100.

  • Use 4 spaces instead of tabs.

  • End all files with a newline.

Documentation and Comments#

  • Do a good job of commenting. Read this Coding Horror article.

  • Comments should add, not repeat: avoid repeating in English or pseudo-code what the code does. Rather, discuss what the block is trying to achieve.

  • Side effects should be visible on screen; if not in code, then in comments.

  • Remember, the best documentation is clean, simple code with good variable names. When this is not possible, you must use a comment to explain the purpose of a functional block.

    Example:

    The following code

    # z must not be greater than 255.
    if z > 255:
        raise RuntimeError('z must be <= 255!')
    

    would be much more informative as

    # If z is greater than 255, this universe will collapse.
    # See https://url.to.issue.tracker/IS-42
    if z > 255:
        raise RuntimeError('z must be <= 255!')
    

    or even better:

    # See https://url.to.issue.tracker/IS-42
    if z > 255:
        raise RuntimeError('z cannot be greater than 255, or this universe will collapse.')
    

Python#

Python Version#

Each package declares the Python versions it supports in its package metadata (requires-python in pyproject.toml or python_requires in setup.cfg or setup.py). Code must be compatible with every version in that range, which should stay within the supported versions of Python (those with “bugfix” or “security” status).

pep8#

As a baseline, follow the pep8 style guide for python.

We do make one exception for maximum line length. In Ocean we maintain a hard limit of 120 characters. It is encouraged but not required to keep lines of code to 100 characters or fewer and docstrings/comments to 72 characters or fewer.

Documentation#

  • Google docstrings convention (definition, example) on all public-facing functions. The following are exceptions:

    • For D-Wave extensions of third-party projects, we match the existing convention (e.g. the D-Wave NetworkX project follows NumPy conventions).

    • Argument defaults are written “default=x” rather than “default x”.

  • Private functions should include some sort of docstring.

  • If your module has more than one public unit, it should have a module docstring with a table of contents.

  • The docstring for the __init__ method goes on the class.

  • All docstrings should be parsable by the Sphinx documentation generation tool (i.e. reStructuredText) The sphinx theme should be readthedocs.

C++#

C++ Version#

C++ code should be compatible with standard C++17.

See PyPA’s docs on C++ standards for a discussion on how this interacts with Python wheels.

Format#

  • Our format is based on Google C++ style guide with some exceptions:

    • Column width is limited to 100 characters. Best effort should be made to keep to 80 characters, but up to 100 can be used for clarity.

    • The base indent level is 4.

    • Non-const references are allowed.

  • When starting a new C++ project, use a .clang-format file

---
Language: Cpp
BasedOnStyle: Google

ColumnLimit: 100
NamespaceIndentation: None

# Scaled by a factor of 2 such that the base indent is 4
AccessModifierOffset: -3
IndentWidth: 4
ContinuationIndentWidth: 8
ConstructorInitializerIndentWidth: 8
...

Versioning Scheme#

Our code follows Semantic Versioning conventions: major.minor.patch.

A change that breaks backwards compatibility must increment the major version. Anything below version 1.0.0 can break backwards compatibility.

Readme File#

If you are creating a repository, don’t forget to include a README.rst containing a reasonable description of your project.