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 ...

Hive Changes
* item 2 ...
* item 3 ...
  continue item 3 ...

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

• General
• Security
• JDBC
• Web UI
• Connectors
• Verifier
• Resource Groups
• SPI

Order of changes

• Fixes: line starts with Fix ...
• Optimizations: line starts with Improve ...
• Additions: line starts with Add...
• Deletions: line starts with Remove...
• Renames: line starts with Rename...

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.

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>`
:doc:`/functions/qdigest`
:issue:`12345`
:pr:`12345`