docs: move whatsnew (SciTools#4540)

* docs: move whatsnew * rebase changes * rebase latest changes
lbdreyer · Jan 31, 2022 · 3cbb687 · 3cbb687
1 parent 2fa7c59
commit 3cbb687
Show file tree

Hide file tree

Showing 7 changed files with 415 additions and 406 deletions.
diff --git a/docs/src/developers_guide/documenting/whats_new_contributions.rst b/docs/src/developers_guide/documenting/whats_new_contributions.rst
@@ -4,16 +4,21 @@
 Contributing a "What's New" Entry
 =================================
 
-Iris uses a file named ``latest.rst`` to keep a draft of upcoming changes
-that will form the next release.  Contributions to the :ref:`iris_whatsnew`
+Iris uses a file named ``dev.rst`` to keep a draft of upcoming development changes
+that will form the next stable release.  Contributions to the :ref:`iris_whatsnew`
 document are written by the developer most familiar with the change made.
 The contribution should be included as part of the Iris Pull Request that
 introduces the change.
 
-The ``latest.rst`` and the past release notes are kept in
-``docs/src/whatsnew/``. If you are writing the first contribution after
-an Iris release: **create the new** ``latest.rst`` by copying the content from
-``latest.rst.template`` in the same directory.
+The ``dev.rst`` and the past release notes are kept in the
+``docs/src/whatsnew/`` directory. If you are writing the first contribution after
+an Iris release: **create the new** ``dev.rst`` by copying the content from
+``dev.rst.template`` in the same directory.
+
+.. note::
+
+  Ensure that the symbolic link ``latest.rst`` references the ``dev.rst`` file
+  within the ``docs/src/whatsnew`` directory.
 
 Since the `Contribution categories`_ include Internal changes, **all** Iris
 Pull Requests should be accompanied by a "What's New" contribution.
@@ -22,7 +27,7 @@ Pull Requests should be accompanied by a "What's New" contribution.
 Git Conflicts
 =============
 
-If changes to ``latest.rst`` are being suggested in several simultaneous
+If changes to ``dev.rst`` are being suggested in several simultaneous
 Iris Pull Requests, Git will likely encounter merge conflicts. If this
 situation is thought likely (large PR, high repo activity etc.):
 
@@ -43,7 +48,7 @@ situation is thought likely (large PR, high repo activity etc.):
 
 * PR reviewer: review the "What's New" PR, merge once acceptable
 
-These measures should mean the suggested ``latest.rst`` changes are outstanding
+These measures should mean the suggested ``dev.rst`` changes are outstanding
 for the minimum time, minimising conflicts and minimising the need to rebase or
 merge from trunk.
 

diff --git a/docs/src/developers_guide/release.rst b/docs/src/developers_guide/release.rst
@@ -183,9 +183,9 @@ back onto the ``SciTools/iris`` ``main`` branch.
 
 To achieve this, first cut a local branch from the latest ``main`` branch,
 and `git merge` the :literal:`.x` release branch into it. Ensure that the
-``iris.__version__``, ``docs/src/whatsnew/index.rst`` and ``docs/src/whatsnew/latest.rst``
-are correct, before committing these changes and then proposing a pull-request
-on the ``main`` branch of ``SciTools/iris``.
+``iris.__version__``, ``docs/src/whatsnew/index.rst``, ``docs/src/whatsnew/dev.rst``,
+and ``docs/src/whatsnew/latest.rst`` are correct, before committing these changes
+and then proposing a pull-request on the ``main`` branch of ``SciTools/iris``.
 
 
 Point Releases
@@ -218,9 +218,11 @@ Release Steps
 #. Update the ``iris.__init__.py`` version string e.g., to ``1.9.0``
 #. Update the ``whatsnew`` for the release:
 
-    * Use ``git`` to rename ``docs/src/whatsnew/latest.rst`` to the release
+    * Use ``git`` to rename ``docs/src/whatsnew/dev.rst`` to the release
       version file ``v1.9.rst``
-    * Use ``git`` to delete the ``docs/src/whatsnew/latest.rst.template`` file
+    * Update the symbolic link ``latest.rst`` to reference the latest
+      whatsnew ``v1.9.rst``
+    * Use ``git`` to delete the ``docs/src/whatsnew/dev.rst.template`` file
     * In ``v1.9.rst`` remove the ``[unreleased]`` caption from the page title.
       Note that, the Iris version and release date are updated automatically
       when the documentation is built
@@ -229,11 +231,11 @@ Release Steps
       dropdown at the top of the file, which provides extra detail on notable
       changes
     * Use ``git`` to add and commit all changes, including removal of
-      ``latest.rst.template``
+      ``dev.rst.template`` and update to the ``latest.rst`` symbolic link.
 
 #. Update the ``whatsnew`` index ``docs/src/whatsnew/index.rst``
 
-   * Remove the reference to ``latest.rst``
+   * Remove the reference to ``dev.rst``
    * Add a reference to ``v1.9.rst`` to the top of the list
 
 #. Check your changes by building the documentation and reviewing
@@ -254,13 +256,6 @@ Post Release Steps
    `Read The Docs`_ to ensure that the appropriate versions are ``Active``
    and/or ``Hidden``. To do this ``Edit`` the appropriate version e.g.,
    see `Editing v3.0.0rc0`_ (must be logged into Read the Docs).
-#. Copy ``docs/src/whatsnew/latest.rst.template`` to
-   ``docs/src/whatsnew/latest.rst``.  This will reset
-   the file with the ``unreleased`` heading and placeholders for the
-   ``whatsnew`` headings
-#. Add back in the reference to ``latest.rst`` to the ``whatsnew`` index
-   ``docs/src/whatsnew/index.rst``
-#. Update ``iris.__init__.py`` version string to show as ``1.10.dev0``
 #. Merge back to ``main``
 
 

diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -98,6 +98,15 @@ For **Iris 2.4** and earlier documentation please see the
    generated/gallery/index
 
 
+.. toctree::
+   :maxdepth: 1
+   :caption: What's New in Iris
+   :hidden:
+
+   whatsnew/latest
+   Archive <whatsnew/index>
+
+
 .. toctree::
    :maxdepth: 1
    :caption: User Guide
@@ -154,6 +163,5 @@ For **Iris 2.4** and earlier documentation please see the
    :hidden:
 
    generated/api/iris
-   whatsnew/index
    techpapers/index
    copyright