From 7897c8f6af3007b8a537247fe150e390a4202865 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 29 Oct 2025 12:32:33 +0100 Subject: [PATCH] Add a docs page with common steps to review the release notes (#19109) --- changelog.d/19109.doc | 1 + docs/SUMMARY.md | 2 ++ .../release_notes_review_checklist.md | 12 ++++++++++++ scripts-dev/release.py | 5 ++++- 4 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 changelog.d/19109.doc create mode 100644 docs/development/internal_documentation/release_notes_review_checklist.md diff --git a/changelog.d/19109.doc b/changelog.d/19109.doc new file mode 100644 index 000000000..4cce54b48 --- /dev/null +++ b/changelog.d/19109.doc @@ -0,0 +1 @@ +Add [a page](https://element-hq.github.io/synapse/latest/development/internal_documentation/release_notes_review_checklist.html) to the documentation describing the steps the Synapse team takes to review the release notes before publishing them. \ No newline at end of file diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 64869eca8..926a6eb84 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -116,6 +116,8 @@ - [The Auth Chain Difference Algorithm](auth_chain_difference_algorithm.md) - [Media Repository](media_repository.md) - [Room and User Statistics](room_and_user_statistics.md) + - [Releasing]() + - [Release Notes Review Checklist](development/internal_documentation/release_notes_review_checklist.md) - [Scripts]() # Other diff --git a/docs/development/internal_documentation/release_notes_review_checklist.md b/docs/development/internal_documentation/release_notes_review_checklist.md new file mode 100644 index 000000000..c3d4d665b --- /dev/null +++ b/docs/development/internal_documentation/release_notes_review_checklist.md @@ -0,0 +1,12 @@ +# Release notes review checklist + +The Synapse release process includes a step to review the changelog before +publishing it. The following is a list of common points to check for: + +1. Check whether any similar entries that can be merged together (make sure to include all mentioned PRs at the end of the line, i.e. (#1234, #1235, ...)). +2. Link any MSCXXXX lines to the Matrix Spec Change itself: . +3. Wrap any class names, variable names, etc. in back-ticks, if needed. +4. Hoist any relevant security, deprecation, etc. announcements to the top of this version's changelog for visibility. This includes any announcements in RCs for this release. +5. Check the upgrade notes for any important announcements, and link to them from the changelog if warranted. +6. Quickly skim and check that each entry is in the appropriate section. +7. Entries under the Bugfixes section should ideally state what Synapse version the bug was introduced in. For example: "Fixed a bug introduced in v1.x.y" or if no version can be identified, "Fixed a long-standing bug ...". \ No newline at end of file diff --git a/scripts-dev/release.py b/scripts-dev/release.py index 111c184cc..262c1503c 100755 --- a/scripts-dev/release.py +++ b/scripts-dev/release.py @@ -316,7 +316,10 @@ def _prepare() -> None: ) print("Opening the changelog in your browser...") - print("Please ask #synapse-dev to give it a check.") + print( + "Please review it using the release notes review checklist: https://element-hq.github.io/synapse/develop/development/internal_documentation/release_notes_review_checklist.html" + ) + print("And post it in #synapse-dev for cursory review from the team.") click.launch( f"https://github.com/element-hq/synapse/blob/{synapse_repo.active_branch.name}/CHANGES.md" )