Skip to content

Latest commit

 

History

History
53 lines (40 loc) · 2.55 KB

MAINTAINING.md

File metadata and controls

53 lines (40 loc) · 2.55 KB
Raw

Maintainers Guide

This document defines a maintainer as a contributor with merge privileges. The information detailed here is mostly related to Qiskit releases and other internal processes.

Stable Branch Policy

The stable branch is intended to be a safe source of fixes for high-impact bugs and security issues that have been fixed on main since a release. When reviewing a stable branch PR, we must balance the risk of any given patch with the value that it will provide to users of the stable branch. Only a limited class of changes are appropriate for inclusion on the stable branch. A large, risky patch for a major issue might make sense, as might a trivial fix for a fairly obscure error-handling case. A number of factors must be weighed when considering a change:

  • The risk of regression: even the tiniest changes carry some risk of breaking something, and we really want to avoid regressions on the stable branch.
  • The user visibility benefit: are we fixing something that users might actually notice, and if so, how important is it?
  • How self-contained the fix is: if it fixes a significant issue but also refactors a lot of code, it's probably worth thinking about what a less risky fix might look like.
  • Whether the fix is already on main: a change must be a backport of a change already merged onto main, unless the change simply does not make sense on main.

Backporting

When a PR tagged with stable backport potential is merged, or when a merged PR is given that tag, the Mergify bot will open a PR to the current stable branch. You can review and merge this PR like normal.

Documentation Structure

The way documentation is structured in Qiskit is to push as much of the actual documentation into the docstrings as possible. This makes it easier for additions and corrections to be made during development, because the majority of the documentation lives near the code being changed. These docstrings are then pulled into the API Reference section of https://docs.quantum-computing.ibm.com.

Refer to https://qiskit.github.io/qiskit_sphinx_theme/apidocs/index.html for how to create and write effective API documentation, such as setting up the RST files and docstrings.

If changes you are making affect non-API reference content in https://docs.quantum-computing.ibm.com you can open an issue (or better yet a PR) to update the relevant page in https://github.com/Qiskit/documentation. You can also use this repo to suggest or contribute brand new content beyond updates to the API reference.