Release notes process

source/Reviewers/curaterelease.rst

@@ -13,13 +13,13 @@ Curating a Release
     releases/um_test_release
     releases/partner_testing
     releases/software_stack
+    releases/release_notes
     releases/shumlib_release
     releases/mule_release
     releases/other_repos
     releases/jules_release
     releases/um_main_release
     releases/lfric_apps_release
-    releases/release_notes
     releases/standard_suites
     releases/stash_browser
     releases/umdp_release
@@ -164,7 +164,7 @@ Tags and Releases
 
   * From the GitHub repo, select ``releases`` and then ``Draft a new release``.
   * Create a new tag and title the release with the same name, eg. ``vn14.0``.
-  * Select to ``Generate release notes``.
+  * Follow the instructions for :ref:`release_notes`.
   * Then ``Publish release``.
 
 
@@ -200,6 +200,14 @@ release will also have been completed.
 Any potential changes to platform software stacks
 
 
+:ref:`Release Notes <release_notes>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Dependencies**
+These should be prepared just before the release, ready to be included with
+each release.
+
+
 Main Release
 ------------
 
@@ -249,14 +257,6 @@ All LFRic PRs (Apps + Core), Jules Release
 Post Release Tasks
 ------------------
 
-:ref:`Release Notes <release_notes>`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Dependencies**
-Most of this can be done pre-release but some details of commit hashes will be
-dependent on the main release being done.
-
-
 :ref:`Updating Standard Suites <standard_suites>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

source/Reviewers/releases/release_notes.rst

@@ -9,82 +9,88 @@
 Release Notes
 =============
 
-The below shows the trac release notes template previously used. This will want
-editing and the exact location needs deciding for the move to GitHub. However it
-can be used as an initial guide to the sort of information included.
+Release notes are included in each repository that has a release. An overarching
+set of release notes in also included in the simulation-systems wiki pages.
 
-.. code-block::
+Ask key people for input on what should be included. This might include managers
+of involved teams, developers who have contributed multiple PRs, and the Code
+Reviewer pool.
+
+* The repository releases are versioned with ``vnX.Y``. The number varies by repository.
+* The Simulation Systems releases are versioned as ``YYYY.MM.N``.
 
-    [[PageOutline]]
-    -----
-    = UM vnXX.Y User Release Notes =
+Repository Release Notes
+------------------------
 
-    == Summary ==
+When creating a release, use the ``Generate Release Notes`` button to create a
+full list of changes being included. Then above this add a summary section that
+is formatted like this:
 
-    * Release date:
-    * Number of tickets:
+.. code-block::
 
-    === Science highlights ===
+    # <Repository Name> vnX.Y release notes
 
-    === Technical highlights ===
+    Summary statement if appropriate
 
-    === Optimisation highlights ===
+    ## Key Changes
+        * ...
 
-    == Known Issues ==
+        Tip: If lots of these, split into subsections as appropriate
 
-    None
+    ## Breaking Changes
+    _These changes will affect suites upgrading to this release_
+        * ...
 
-    == Revisions and Keywords ==
+        No known breaking changes at this release.
 
-    || Repository || !Keyword/Revision ||
-    || [browser:main UM]                                                    || vnXX.Y = NNNN ||
-    || [https://code.metoffice.gov.uk/trac/jules/browser/main JULES]        || vnA.B = umXX.y = NNNN ||
-    || [https://code.metoffice.gov.uk/trac/monc/browser/casim CASIM]        || etc ||
-    || [https://code.metoffice.gov.uk/trac/socrates/browser/main SOCRATES]  ||     ||
-    || [https://code.metoffice.gov.uk/trac/ukca/browser/main UKCA]          ||     ||
-    || [browser:aux Aux]                                                    ||     ||
+    ## Known Issues
+        * ....
 
-    GCOM and SHUMlib installations should be built using revisions:
+        No known issues at this release.
 
-    || Repository || !Keyword/Revision ||
-    || [https://code.metoffice.gov.uk/trac/gcom/browser/main GCOM]          || vnXX.Y = NNNN ||
-    || [https://code.metoffice.gov.uk/trac/utils/browser/shumlib SHUMlib]   || YYYY.MM.N = NNNN ||
+    ## Linked Changes
+    This release is part of the [YYYY.MM.N Simulation Systems Release.]
+    (https://github.com/MetOffice/simulation-systems/wiki/YYYY.MM.N). All
+    codebases required by <repository>, including <some other repositories>
+    etc, have been tagged ``YYYY.MM.N``.
 
-    Note that SHUMlib may not be released at every UM release.
 
-    For testing purposes, the LFRic Apps and MOCI repositories:
+Simulation Systems Release Notes
+--------------------------------
 
-    || Repository || Revision ||
-    || [browser:main/trunk/rose-stem/rose-suite.conf MOCI]           ||  NNNN  ||
-    || [https://code.metoffice.gov.uk/trac/lfric_apps/browser/main LFRic Apps] ||  vnA.B = umXX.Y = NNNN ||
+Create a new wiki page:
 
-    Required for rose-stem:
+.. image:: images/gh_screenshots/release_notes_light.png
+    :class: only-light border
 
-    {{{#!comment
-    Obtain these by grepping, for example:
-    grep -r CYLC_VERSION ~frzz/cylc-run/um_heads_nightly_YYYY-MM-DD/log/job
-    }}}
+.. image:: images/gh_screenshots/release_notes_dark.png
+    :class: only-dark border
 
-    * Rose vn YYYY.MM.N
-    * Cylc vn YYYY.MM.N
+#. Click the pencil in the `wiki sidebar <https://github.com/MetOffice/simulation-systems/wiki>`_
+   to edit it.
 
-    == Ticket Overview ==
+#. Add the new release YYYY.MM.N to the release notes section and save.
 
-    * Tickets marked as closed/fixed below may not be associated with a ``main`` commit
-    * Only tickets with a UM element are displayed below. Sub-repositories may contain additional standalone tickets that will have been implicitly tested and included in the release.
+#. Click the link in the sidebar you just created to add the new page.
 
-    [[TicketQuery(milestone^=UMXX.Y (MMM-YY),status=closed,resolution=fixed,format=table,col=summary|reporter|keywords)]]
+#. The contents of this page should be formatted like this:
+
+.. code-block::
 
-    == Platforms ==
+    # Simulation Systems YYYY.MM.N Release
 
-    Testing:
-    * Met Office SPICE: [wiki:ReleaseNotesXX.Y/ReleaseTestingAZSPICE]
-    * Met Office EX1A: [wiki:ReleaseNotesXX.Y/ReleaseTestingEX1A]
+    Release date:
 
+    ## Included Releases
+    * [LFRic Apps vnX.Y](https://github.com/MetOffice/lfric_apps/releases/tag/vnX.Y)
+    * [LFRic Core vnX.Y](https://github.com/MetOffice/lfric_core/releases/tag/vnX.Y)
+    * [UM vnX.Y](https://github.com/MetOffice/um/releases/tag/vnX.Y) (private within the MetOffice organisation)
+    * [JULES vnX.Y](https://github.com/MetOffice/jules/releases/tag/vnX.Y) (currently private, will hopefully soon be publically available)
 
-For the highlights section:
+    ## Key Highlights
+    * A few highlights the affect multiple repositories
+    * or that are particularly special and are worth raising the profile of at this level
 
-* Contact HPC Optimisation team (usually AM) to request details for the optimisation section
-* Take some time to think about the 'big picture' relevance of tickets for the science and technical highlights
-* Copy the 'head of ``main``' section and paste underneath, changing the section title to the release.
-* Paste trac.logs into the relevant sub-pages. You'll likely be able to use some nightly testing runs.
+    ## Software Stack Updates
+    * Any package changes to the software stack
+    [Full LFRic Software Stack details](https://metoffice.github.io/lfric_core/getting_started/installation/software_dependencies.html)