Guide to releasing software at Q-CTRL

Every software release at Q-CTRL requires three important pieces of information:

  1. Version
  2. Title
  3. Description

The information is mandatory and follows specific standards that MUST be followed in order to ensure consistency, quality and usefulness for both internal and external customers.

# Version

The version MUST follow the Semantic Versioning standard.

# Title

The title MUST be the project name followed by the version. For example, Q-CTRL Python Open Controls 2.3.4.

# Description

The description MUST consist of at least one of the following sections:

  1. Breaking changes
  2. What’s new
  3. Bug fixes
Breaking changesA list of backwards-incompatible changes to the public API
What’s newA list of new features or functionality a customer would experience or have access to
Bug fixesA list of bugs fixed as part of the release

The sections MUST appear in the above order. If one section is empty, it can be omitted from the description. The contents of each section MUST be an unordered (bulleted) list and MUST adhere to the Q-CTRL style guide.

Use the template below when describing a release.

Breaking changes

- Things
- We
- Broke

What's new

- Things
- We
- Added

Bug fixes

- Things
- We
- Fixed

# Dependencies

Sometimes a release is necessary because of an updated dependency. For example, the Q-CTRL Python package being released because of an updated version of the Q-CTRL Commons Python package. Although the changes may only occur in the dependency project, the changes affecting the upstream project MUST be captured in the release description of that project.