diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 00000000..b5e761c0 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,87 @@ +# Release process for a new version of the CF conventions + + +Complete the following steps in the order presented. + +### Warning + +Be aware that elements of the https://github.com/cf-convention/cf-conventions and https://github.com/cf-convention/cf-convention.github.io repositories may have changed since the previous release, requiring modification to the release procedure. In this case, make a note of the changes and update these instructions after completing the release. + +## Move to the https://github.com/cf-convention/cf-conventions repository + +* Check that all merged pull requests that contributed to the new version have the correct GitHub Milestone (https://github.com/cf-convention/cf-conventions/milestones) attached to them - the milestone has the same name as the new version (e.g. `1.11`). + +* Update the revision history in `history.adoc` + + - Check that the history is up to date. Every pull request merged to the convention document should be referenced. + - Change the `Working version (most recent first)` heading to `Version (
)` (replacing `` with the current version, and `
` with today's date, e.g. `Version 1.11 (05 December 2023)`). + +* Create a new release at https://github.com/cf-convention/cf-conventions/releases by following the instructions at https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes, with the following details: + + - "Choose a tag" for the new version on the `main` branch: The tag should be called `v.0` (replacing `` with the current version, e.g. `v1.11.0`). + - Set the release title to `CF-` (replacing `` with the current version, e.g. `CF-1.11`). + - Click "Generate release notes". This will automatically generate a description of the release. + - Edit the description to remove the list of contributors, instead adding any new people who have made substantive contributions to the list at http://cfconventions.org/conventions_contributors.html. + - Select "Set as the latest release". + - Select "Publish release". + +* Get the new documents from the "Artifacts" section of the latest run of the "Build Workflow" GitHub Action, which will be called `CF-` (where `` is thethe current version, e.g. `CF-1.11`) at https://github.com/cf-convention/cf-conventions/actions, saving them locally: + + - `conformance_docs.zip` + - `conventions_docs.zip` + +* Unzip the downloaded artifacts to get the HTML and PDF builds of the conventions and conformance documents, and the `images` directory. These will be used in the next section. + + - `conformance.html` + - `conformance.pdf` + - `cf-conventions.html` + - `cf-conventions.pdf` + - `images/` + +* Increment the version in `version.adoc` (which records the _next_ release). + +* Update the revision history in `history.adoc`, again: + + - Reinstate the `=== Working version (most recent first)` heading at the top. This is required for the new draft release of the _next_ version. + +## Move to the https://github.com/cf-convention/cf-convention.github.io repository + +### Add the release documents + +* Add the new release documents (that have been downloaded and unpacked from the GitHub actions, see the previous section) into the `Data` folder as follows (replacing `` with the current version, e.g. `1.11`): + + - `Data/cf-conventions/cf-conventions-/cf-conventions.html` + - `Data/cf-conventions/cf-conventions-/cf-conventions.pdf` + - `Data/cf-conventions/cf-conventions-/images/*` + - `Data/cf-documents/requirements-recommendations/conformance-.html` + - `Data/cf-documents/requirements-recommendations/conformance-.pdf` + +### Update website links and headings for the new version + +* The following files need updating: + + * conventions_contributors.md + - Add any new contributors (see the above note in "Create a new release"). + + * `conventions.md` + - Add a new HTML entry for the new version of the conventions documents + - Increment the draft version of the conventions documents. + - Remove the "latest released version" text from the previous latest release. + - Add a new HTML entry for the new version of the conformance document + - Increment the draft version of the conformance documents. + + * `documents.md` + * `faq.md` + - Update CF version number. + + * `index.md` + - Update CF version number. + + * `software.md` + - Update CF version number. + +* Check for any other occurences of hard-wired version numbers in any file. + +## Announce the release + +* Wait until all changes are visible via the web site, and then announce the release on the `discuss` repository issue tracker: https://github.com/cf-convention/discuss/issues (note that there may already be a open issue in which to do this.