Release Notes Guidelines

Overview

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

Order of sections

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

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 changes

• Fixes: line starts with Fix ...
• Optimizations: line starts with Improve ...
• Additions: line starts with Add...

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`