Jules Release#

Create Branch#

Ensure you have a fork of the jules repository, and that the main branch is up to date with the upstream repository.

In a clone of this fork, create a branch using the main branch as the parent.

Important

Ensure you create branches from main, otherwise you will not include the changes from the past release.

Metadata Changes#

  • First, change the user guide URLs in the HEAD metadata for jules-fcm-make and jules-standalone from “latest”. This is done automatically by running the create_jules_version_metadata.py script from the rose-stem directory.

    cd rose-stem
./bin/create_jules_version_metadata.py 5.8 5.9

  • Run rose config-dump to ensure that the metadata files are in the common format (do this from the top-level of the clone)

  • Copy rose-meta/jules-standalone/versions.py to an appropriately named file, e.g. for the JULES vn5.9 release, the file is called rose-meta/jules-standalone/version58_59.py.

    cp rose-meta/jules-standalone/versions.py rose-meta/jules-standalone/version58_59.py

  • Edit rose-meta/jules-standalone/versions.py to:

    • Remove the upgrade macros

    • Import the macros from the newly created file, e.g.

    ...
from .versionUU_YY import *
...

class vnYY_txxxx(MacroUpgrade):

    """Upgrade macro from JULES by Author"""

    BEFORE_TAG = "vnY.Y"
    AFTER_TAG = "vnY.Y_txxxx"

    def upgrade(self, config, meta_config=None):
        """Upgrade a JULES runtime app configuration."""

        # Add settings
        return config, self.reports

  • Edit rose-meta/jules-standalone/version<from>_<to>.py such that,

    • Imports of other macros are removed

    • Add a new blank upgrade macro that bumps the version to the release version,

      class vn58_vn59(MacroUpgrade):
    """Version bump macro"""

    BEFORE_TAG = "vn5.8_txxx"
    AFTER_TAG = "vn5.9"

    def upgrade(self, config, meta_config=None):
        # Nothing to do
        return config, self.reports

    • Add a similar version bump macro to rose-meta/jules-fcm-make/versions.py.

  • Check that the list of options on line 96 in rose-meta/jules-fcm-make/HEAD/rose-meta.conf includes all the ones listed in directory etc/fcm-make/platform/ (ignoring custom.cfg, envars.cfg and load_settings.cfg).

  • Commit the metadata changes

Rose Stem Updates#

  • Update the VN variable in rose-stem/rose-suite.conf.

  • Upgrade the rose-stem apps as normal, using the upgrade macro added earlier, e.g.

    ./bin/upgrade_jules_test_apps vn5.9

  • Update KGO_VERSION in rose-stem/include/variables.cylc to the release version, making a note of original version number.

  • Login as julesadmin and create new KGO directories for the release by copying the old kgo to a new directory named vnX.Y. See the kgo install instructions for paths to the kgo install.

  • Commit the rose-stem changes and then run the Jules and UM rose-stem suites to ensure nothing has broken.

Code Review and Commit#

With a reviewer, follow the release process.

Release Notes#

todo

Jules Release Documentation

These are done with a PR in this GitHub repo

Often the release notes will have been prepared beforehand and have their own PR. In this case it makes more sense for you to review and commit that branch. See below for the relevant steps and the how to commit page for instructions.

The user guide contains release notes for each JULES version which should detail any major commits.

  1. Create a new file at user_guide/doc/source/release_notes/JULESX-X.rst, probably by copying from a previous release

  2. Go through the main commits since the last release and decide whether the change is worth noting

  3. Use the PR details to describe the change

  4. For some large commits, it is worth contacting the original author for a few sentences

  5. Add the new file to the contents, at the top - user_guide/doc/source/release_notes/contents.rst

  6. Update the version number in docs/user_guide/source/conf.py and check the copyright variable is correct.

To build the docs, move into the user_guide/doc directory. At meto, module load scitools will also need to have been run.

# For html pages
make html
firefox build/html/index.html

# For latex pdfs
make latexpdf
gio open build/latex/JULES_User_Guide.pdf

Publicise the Release#

Update the wiki:

  • Update the table on the front page of this wiki to note the release.

  • Create a new standard jobs page for the upcoming release cycle - compare the list of apps in the table to that in the rose-stem/apps directory.

  • Mark the wiki milestone for the release as completed (this should give the option to move open PRs to a different milestone)

Notify the JULES community: