Release Notes Guidelines

Overview

Release notes describe user-impacting changes coming with a specific Presto version.

Every pull request should include its relevant release notes. When creating a pull request, the description section has been pre-populated with instruction to fill in the release notes. Place the release notes at the bottom of the PR description. An empty line separates two sections. Long lines can be wrapped with no leading asterisk (*). For example:

== RELEASE NOTES ==
General Changes
* item 1 ... :pr:`12345`

Hive Connector Changes
* item 2 ... :pr:`12345`
* item 3 ... 
  continue item 3 ... :pr:`12345`

Edit 12345 to include the new pull request number in the release notes entry.

If release notes are not required for a pull request, add the tag at the bottom of the PR description:

== NO RELEASE NOTE ==

When adding release notes or the no-release-note tag, wrap the section with a pair of triple backticks (```). This prevents the list items being markdown-formatted.

Section naming

Section names should end with Changes, e.g., General Changes, SPI Changes.

For connectors, names should end with Connector Changes, e.g., Hive Connector Changes. This provides consistency as some connectors such as Memory would be ambiguous without saying Connector, thus we use the same language for all of them to avoid the need to decide if the name would be ambiguous.

Order of sections

Add release notes grouped by sections in the following order of components

General
Prestissimo (Native Execution)
Security
JDBC
Web UI
Connectors
Verifier
Resource Groups
SPI
Documentation

Order of changes

Within each section add release notes in the order of the following categories

Fixes: line starts with Fix ...
Optimizations: line starts with Improve ...
Additions: line starts with Add...
Replacements: line starts with Replace...
Renames: line starts with Rename...
Deletions: line starts with Remove...
Dependency version updates: line starts with Upgrade/Downgrade...

Phrasing

Use imperative present to describe change. When a change adds configuration, tell if it is a configuration property or a session property. Describe the functionality first and then the configuration entries:

* Add support for grouped execution for queries with no joins or aggregations.
  This can be enabled with the ``grouped_execution_for_eligible_table_scans``
  session property or the
  ``experimental.grouped-execution-for-eligible-table-scans-enabled``
  configuration property.

In case the configuration property or the session property is the feature itself and not a part of a bigger feature, start with the property name and what it does.

* Add session property ``optimize-top-n-row-number`` and configuration property
  ``optimizer.optimize-top-n-row-number`` to toggle the top N row number
  optimization.

If a pull request was created in response to a CVE or other security announcement, link to the CVE in the release note entry.

* Upgrade okio to 3.6.0 in response to `CVE-2023-3635 <https://github.com/advisories/GHSA-w33c-445m-f8w7>`_. :pr:`23796`

Audience

A release note should be understandable to end users of Presto. The audience - who you are writing to in the release note - are not necessarily developers knowledgable of the Presto codebase, but are more often data engineers and other people who want to quickly understand the change described by the release note. A release note entry should be both concise and understandable to lay people.

Documentation-only Pull Requests

Documentation-only PRs that correct errors of content or formatting should be tagged as

== NO RELEASE NOTE ==

Documentation-only PRs that add documentation of a function, connector, or other feature, should be tagged as General Changes, as follows:

== RELEASE NOTES ==
General Changes
* item 1 ... :pr:`12345`

Formatting

Use verbatim monospace blocks for types, SQL keywords and configuration properties:

``TINYINT``
``ORDER BY``
``query-manager.required-workers``

Use Sphinx RestructuredText hyperlinking capabilities to cross-reference documentation:

:func:`ngrams`
:ref:`qdigest <qdigest_type>`
:ref:`admin/properties:\`\`join-distribution-type\`\``
:doc:`/functions/qdigest`
:issue:`12345`
:pr:`12345`