Skip to main content

Release Notes

This page describes the process for creating release notes for users of Scalar products, which includes enterprise customers and open-source software users, to read.

Who the audience is for release notes​

Release notes are mainly for external users to reference.

Although Scalar employees can reference release notes to gain a high-level understanding of changes in a product release, release notes are intended for users to read. Therefore, keep in mind what you expect users will want to read and what particular details.

When to write release notes​

Write release notes for each major, minor, or patch version release when the changes are user facing.

warning

When changes aren't user facing, don't write release notes. Some examples of non-user-facing changes include the following:

  • CI-related changes
  • Code refactoring
  • Library version updates

How to write release notes​

The following explains how to format, categorize, and write release notes.

General guidelines​

  • Put release note text in the ## Release notes section in the pull request (PR) that contains your changes.
    • Note that the release note script picks up all content below the ## Release notes section heading.
  • Only write release notes if the changes in the PR are user facing, as described in the When to write release notes section.

Format​

  • To include release note text in published release notes, write a description below the ## Release notes section in the PR template.
    • For guidance on choosing the right category, see Categories.
    • For guidance on writing a good description, see Descriptions.

Categories​

The category that you choose for the release note should match the label that's selected in the PR. Although you may select multiple labels in a PR, only one of the categories from the following table should be selected in the corresponding PR.

CategoryFocus
backward-incompatibleBackward-incompatible changes (for example, changes that cause issues or break usage) to Scalar products. Examples include changes to commands, endpoints, logging, and SQL statements.
enhancementAdditions (for example, new functions or support for new databases) to the product that are only backward compatible.
improvementChanges that improve existing functions and performance, like at the storage and SQL engine levels.
bugfixChanges that fix known problems as opposed to add or improve functionality.

Descriptions​

  • To provide a comprehensive explanation to users, default to including more information rather than too little information.
  • Each release note should answer the following:
    • What changed in this release?
    • How was that change implemented?
    • Why is this change relevant?
  • Use past tense (for example, "Added support for ....", "Fixed a bug in ....").
    • When necessary to avoid awkward or unnatural sentence constructions, you may also use present tense (for example, "ScalarDB now supports ....").

Examples​

The following are some examples of PRs with release note text.

PR with a single release note sentence​

A single-sentence release note in a PR should look as follows:

## Release notes

Added validation for the consensus commit mutation operation.

PR with multiple release note sentences​

A multi-sentence release note in a PR should look as follows:

## Release notes

Integrated the ScalarDB GraphQL and ScalarDB SQL interfaces with ScalarDB Cluster. As of ScalarDB 3.9, you no longer need to deploy dedicated components to provide GraphQL and SQL interfaces, respectively. In addition, you can more easily manage a ScalarDB Cluster.

PR with a release note for a bug fix​

A release note in a PR that fixes a CVE-listed bug should look as follows:

## Release notes

Upgraded the gRPC library to 1.53.0 to fix security issues. [CVE-2023-1428](https://nvd.nist.gov/vuln/detail/CVE-2023-1428) [CVE-2023-32731](https://nvd.nist.gov/vuln/detail/CVE-2023-32731)

PR without release note text​

For details about which types of changes don't need release note text, see the When to write release notes section.

For PRs that don't need release note text, use the following format:

## Release notes

N/A

PR with related PRs in the same repository (without additional release note text)​

Add a link to the topic PR that exists in the same repository as the one in which you are creating the related PR in (for example, if both PRs exist in the scalardb repository).

Topic PR​

Original release note text.

## Release notes

Added an interface to `Scan` to allow conditions (AND, OR, etc.) to be specified.

Write Same as #<TOPIC_PR_NUMBER>, replacing #<TOPIC_PR_NUMBER> with the number from the topic PR in the same repository.

## Release notes

Same as #1234

PR with related PRs in the same repository (with additional release note text)​

Add a link to the topic PR that exists in the same repository as the one in which you are creating the related PR in (for example, if both PRs exist in the scalardb repository). Then, write additional release note text as follows.

note

In this case, this additional release note text will be added to the end of the release note text from the topic PR.

Topic PR​

Original release note text.

## Release notes

Added functionality to treat the transaction metadata columns in a record as committed if the metadata in ScalarDB is empty (null).

Write Same as #<TOPIC_PR_NUMBER>, replacing #<TOPIC_PR_NUMBER> with the number from the topic PR in the same repository, followed by the additional release note text.

## Release notes

Same as #1234

This functionality allows ScalarDB to import tables from another existing database.

Don't add links to related PRs that exist in a different repository than the one in which you are creating the PR in (for example, if one PR exists in the scalardb repository and another PR exists in the scalardb-samples repository). Instead, add the release note text from the related PR in that repository.

PR in the scalardb-samples repository​

## Release notes

Added an interface to `Scan` to allow conditions (AND, OR, etc.) to be specified.

PR in the scalardb repository​

## Release notes

Added an interface to `Scan` to allow conditions (AND, OR, etc.) to be specified.