From 67829183fc32dfff434de27aa0cb63616a842982 Mon Sep 17 00:00:00 2001
From: Marc White <marc.white@anu.edu.au>
Date: Wed, 11 Dec 2024 14:40:53 +1100
Subject: [PATCH] Post v1.0.0 release documentation updates (#302)

---
 docs/management/release.rst | 25 +++++++++++++++++++++++++
 docs/project_list.rst       | 14 +++++++-------
 docs/storage_flags.rst      |  2 +-
 3 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/docs/management/release.rst b/docs/management/release.rst
index d2f5348..cf701f9 100644
--- a/docs/management/release.rst
+++ b/docs/management/release.rst
@@ -15,6 +15,13 @@ or may not include an update to the ACCESS-NRI catalog files on Gadi.
 
 #. Enter the new version (vX.X.X) as the tag and release title. Add a brief description of the release.
 
+   .. note::
+
+      It is recommended to attempt a beta release before committing to a major code update.
+      In this case, the version number requires an ordinal after the :code:`b`, e.g., :code:`vYYYY-MM-DDb0`. If the
+      ordinal isn't provided, the GitHub PyPI build action will append one, which breaks the linkage
+      between the PyPI and Conda build actions.
+
 #. Click on "Publish release". This should create the release on GitHub and trigger the workflow that builds and uploads 
    the new version to PyPI and conda
 
@@ -35,9 +42,27 @@ Generating a new catalog version
      $ cd bin
      $ qsub -v version=${RELEASE} build_all.sh
 
+   .. note::
+      Running the build script requires access to an up-to-date checkout of the :code:`access-nri-intake-catalog`
+      repository. The default location for this is :code:`/g/data/xp65/admin/access-nri-intake-catalog`. If you do 
+      not have the ability to update this checkout, you may use a local one; however, you will need to update
+      the :code:`CONFIG_DIR` variable in :code:`bin/build_all.sh` to point at your checkout location.
+
    .. note:: 
       If :code:`version` is not provided, the default used is the current date, in the format :code:`vYYYY-MM-DD`. This should 
       be acceptable in most cases.
     
 #. Updating :code:`access_nri_intake_catalog` is no longer necessary - the new catalog will be available immediately as 
    :code:`intake.cat.access_nri`.
+
+
+New release with new catalog
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the case of a linked release of a new major :code:`access-nri-intake-catalog` and a new catalog 
+build, the recommened process is:
+
+#. Create a beta release of :code:`access-nri-intake-catalog`;
+#. Use the beta release to build a new catalog;
+#. Iterate over the above steps until the desired result is achieved;
+#. Make a definitive code release.
\ No newline at end of file
diff --git a/docs/project_list.rst b/docs/project_list.rst
index 37c0f32..214015e 100644
--- a/docs/project_list.rst
+++ b/docs/project_list.rst
@@ -1,13 +1,13 @@
-* :code:`py18`
-* :code:`xp65`
-* :code:`ik11`
-* :code:`cj50`
-* :code:`zz63`
+* :code:`rr3`
 * :code:`rt52`
+* :code:`hq89`
+* :code:`zz63`
 * :code:`al33`
 * :code:`oi10`
-* :code:`rr3`
+* :code:`ik11`
 * :code:`ig45`
-* :code:`hq89`
 * :code:`fs38`
 * :code:`p73`
+* :code:`xp65`
+* :code:`py18`
+* :code:`cj50`
diff --git a/docs/storage_flags.rst b/docs/storage_flags.rst
index 41cbfe9..8e5e17c 100644
--- a/docs/storage_flags.rst
+++ b/docs/storage_flags.rst
@@ -1,3 +1,3 @@
 .. code-block::
 
-   gdata/py18+gdata/xp65+gdata/ik11+gdata/cj50+gdata/zz63+gdata/rt52+gdata/al33+gdata/oi10+gdata/rr3+gdata/ig45+gdata/hq89+gdata/fs38+gdata/p73
\ No newline at end of file
+   gdata/rr3+gdata/rt52+gdata/hq89+gdata/zz63+gdata/al33+gdata/oi10+gdata/ik11+gdata/ig45+gdata/fs38+gdata/p73+gdata/xp65+gdata/py18+gdata/cj50
\ No newline at end of file