Draft Release Template

Templates
1

To receive email notifications when a new release is announced, please [watch] this topic.

PRODUCT NAME
:rocket: Release: N.N.N

Short blurb or what the product is and the major changes in this release.

How to use:
Refer to LINK TO USER GUIDE

Features:

:white_check_mark: Feature 1
:white_check_mark: Feature 2
:white_check_mark: Feature 3

Known Issues / Limitations:
:warning: Add any warnings as appropriate here, or delete.
:stop_sign: Limitation 1
:stop_sign: Limitation 1
:stop_sign: Limitation 1

Resources:

  • Link to docs
  • Link to GitHub etc.

Internal checklist before model release:
decide alpha/beta/full (ref to this table and guidance doc)
choose build version, create release (example)
choose config versions, create release (example)
- decide what changes should be in a release
- resolutions/forcings are being released
- review if any major issues should prevent release
check (configuration? access-hive?) docs are accurate and point towards them in release document (create zenodo DOI version as needed)
draft a forum release note (inc. known issues) and have a review. Ensure that it appears here.
if alpha release:

  • check that it is written how to to run release
  • consider drafting a release post but don’t post it

update model release record

2

I’d plump for a “Credits” section

3

In the spirit of pedantry, I think I’d prefer “How to use” to “Getting started”. If someone is already using a released product and wants to update to the more recent version “Getting started” doesn’t seem as appropriate.

This is a musing more than anything. I’ve not even managed to convince myself, but thought it worth mentioning.

4

In a similar vein, “Resources” instead of “Further Reading”?

5

Do we need a section for Breaking Changes?

Do we need a section for Test Results ? (optimistic, I know!)

Github links are good, but should we also have a gadi address (i.e. which module to use)

I think the sections should be more explicit:

i.e.

  • Limitations should have links to github issues and any known issues should be put into issues before the release is made
  • Link to github should be a link to the Github release
6

Do we have a process for incorporating (or rejecting) suggested changes?

I’ve added “Known Issues” heading above the warnings in my first use of the template, as I think it is important to at least imply this might be something we will fix at a later date.

7

Definitely also need a boiler-plate “How to get support” section.

8

I’ve added some of the suggestions to the template - I think this will be somewhat organic and change slightly for the specific release. We can re-evaluate as time goes on.

9

I’ve modified to more closely reflect current usage. This includes adding a support section, changing the visibility of credits, and splitting the known issues and warnings.

We can change back or modify as required.

One formatting change was to use markdown titles. This has the advantage that it creates an anchor to that section so it can be linked to directly.