From 3b1fc2c9a269425ac0ea6d5c56a54a1fa24a7f9d Mon Sep 17 00:00:00 2001
From: Manfred Moser <manfred@simpligility.ca>
Date: Wed, 8 Nov 2023 15:49:04 -0800
Subject: [PATCH] Improve breaking change release notes render

---
 docs/src/main/sphinx/conf.py                |  4 ++++
 docs/src/main/sphinx/release.md             | 17 +++++++++++++++++
 docs/src/main/sphinx/release/release-432.md |  4 ++--
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/docs/src/main/sphinx/conf.py b/docs/src/main/sphinx/conf.py
index 158fe1f2792a..baa17cfe1cfc 100644
--- 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
index 62a1407ff714..b92f2e50d73f 100644
--- 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
index 176ef6a6cbdf..2f334fda69dc 100644
--- 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`)