Add a docs page with common steps to review the release notes (#19109)

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.

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

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: <https://github.com/matrix-org/matrix-spec-proposals/pull/xxxx>.
+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 ...".

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"
     )