Improve breaking change release notes render

trinodb · Nov 9, 2023 · 3b1fc2c · 3b1fc2c
1 parent 36895bb
commit 3b1fc2c
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 2 deletions.
diff --git a/docs/src/main/sphinx/conf.py b/docs/src/main/sphinx/conf.py
@@ -119,6 +119,10 @@ def setup(app):
     "substitution"
 ]
 
+myst_substitutions = {
+    "breaking": "<a href='../release.html#breaking-changes' title='Breaking change'>⚠️</a>"
+}
+
 # -- Options for HTML output ---------------------------------------------------
 
 html_theme = 'sphinx_material'

diff --git a/docs/src/main/sphinx/release.md b/docs/src/main/sphinx/release.md
@@ -357,3 +357,20 @@ release/release-0.56
 release/release-0.55
 release/release-0.54
 ```
+
+## Breaking changes
+
+Starting with Trino 432, release notes include a ⚠️ symbol to highlight any
+changes as potentially breaking changes. The following changes are considered
+and may require adjustments:
+
+* Removal or renaming of configuration properties that may prevent startup or
+  require configuration changes
+* Changes to default values for configuration properties that may significantly
+  change the behavior of a system
+* Updates to the requirements for external systems or software used with Trino,
+  such as removal of support for an old version of a data source in a connector
+* Non-backwards compatible changes to the SPI which may require plugins to be
+  updated
+* Otherwise significant changes that requires specific attention from teams
+  managing a Trino deployment
diff --git a/docs/src/main/sphinx/release/release-432.md b/docs/src/main/sphinx/release/release-432.md
@@ -20,7 +20,7 @@ adjustments:
 
 * Improve performance of `CREATE TABLE AS ... SELECT` queries that contain a redundant
   `ORDER BY` clause. ({issue}`19547`)
-* ⚠️ Remove support for late materialization, including the
+* {{breaking}} Remove support for late materialization, including the
   `experimental.late-materialization.enabled` and
   `experimental.work-processor-pipelines` configuration properties. ({issue}`19611`)
 * Fix potential query failure when using inline functions. ({issue}`19561`)
@@ -59,5 +59,5 @@ adjustments:
 ## SPI
 
 * Add Trino version to SystemAccessControlContext. ({issue}`19585`)
-* ⚠️ Remove null-suppression from RowBlock fields. Add new factory methods to
+* {{breaking}} Remove null-suppression from RowBlock fields. Add new factory methods to
   create a `RowBlock`, and remove the old factory methods. ({issue}`19479`)