From cb89d3f21f42e1aa4ebceabdb0df3870ace7f111 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Mon, 16 Oct 2023 09:36:03 +0200 Subject: [PATCH] add release process to the docs (#668) Fixes #499 The process is not yet optimal, but this describes the current situation. I opened #666, #667 and #669 with some ideas for improvements. --- docs/_quarto.yml | 1 + docs/contribute/index.qmd | 1 + docs/contribute/python.qmd | 2 +- docs/contribute/release.qmd | 105 ++++++++++++++++++++++++++++++++++++ 4 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 docs/contribute/release.qmd diff --git a/docs/_quarto.yml b/docs/_quarto.yml index cd60d14a0..9f7b2891a 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -48,6 +48,7 @@ website: - contribute/core.qmd - contribute/python.qmd - contribute/addnode.qmd + - contribute/release.qmd format: html: diff --git a/docs/contribute/index.qmd b/docs/contribute/index.qmd index 54a102654..a852114cd 100644 --- a/docs/contribute/index.qmd +++ b/docs/contribute/index.qmd @@ -6,3 +6,4 @@ Ribasim welcomes contributions. There is developer documentation for the [Julia core](core.qmd) and [Python tooling](python.qmd). A guide on how to add a new node type to both is written in [adding node types](addnode.qmd). +[Release process](release.qmd) describes the steps to follow when creating a new Ribasim release. diff --git a/docs/contribute/python.qmd b/docs/contribute/python.qmd index 07ece0824..2a3abb1c5 100644 --- a/docs/contribute/python.qmd +++ b/docs/contribute/python.qmd @@ -45,7 +45,7 @@ If the example models change, re-run this script. 2. Copy `.vscode/settings_template.json` into `.vscode/settings.json` -## How to publish to PyPI +## How to publish to PyPI {#sec-pypi} 1) Update `__version__` in `ribasim/__init__.py` diff --git a/docs/contribute/release.qmd b/docs/contribute/release.qmd new file mode 100644 index 000000000..86c2ac085 --- /dev/null +++ b/docs/contribute/release.qmd @@ -0,0 +1,105 @@ +--- +title: "Release process" +--- + +# What is a release + +The [Ribasim repository](https://github.com/Deltares/Ribasim) contains several components, e.g., the Julia core, the Python tooling and QGIS plugin. +The components are currently only guaranteed to work together if they are built at the same time. +Therefore we release Ribasim as a collection of all the components at once. +For maximum interoperability it is suggested to only release all components together, and not individually. + +For these releases we use [Calender Versioning](https://calver.org/), which makes it clear in which month the release was made. + +# Release steps + +This section provides a guide for developers to follow when preparing a new release. + +## Pre-release checks + +Before starting the release process, ensure that all tests are passing and that all features intended for the release are complete and merged into the main branch. + +## Update version numbers of the components as needed + +The components have their own version number which generally uses [Semantic Versioning](https://semver.org/), with minor version signifying a breaking release for pre-1.0 versions, as [documented here](https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0). If a component did not change at all between releases, the version number can stay the same. + +Now submit a pull request which updates the version numbers of the components as needed. +You can use [PR #623](https://github.com/Deltares/Ribasim/pull/623) as an example. + +In general for Python packages the version number is in `__init__.py`, for Julia it is `Project.toml`, and for QGIS `metadata.txt` + +## Update the wheel links {#sec-wheel-links} + +The nightly download links for the Ribasim Python wheels contain the version number. Search for "any.whl" and update these to the new version number of Ribasim Python. + +## Create a new release + +Create a [new release](https://github.com/Deltares/Ribasim/releases/new). +Give it a tag like `v2023.08.0`, filling in the current year, month and a sequential "MICRO" number. +This follows `vYYYY.0M.MICRO` from [calver](https://calver.org/). +For [v2023.09.0](https://github.com/Deltares/Ribasim/releases/tag/v2023.09.0) I used the "Generate release notes" button, which I then manually edited to copy the most important changes for users to the top in the form of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +The possibly long list of generated release notes can put below an "All changes" collapsed item as such: + +``` +
+ +All changes + + +# Put Github flavored markdown here + +
+ +``` + +## Release Ribasim Python to PyPI + +To be able to do `pip install ribasim`, Ribasim Python needs to be released on the Python Package Index, see [these instructions](python.qmd#sec-pypi) + +## Wait for TeamCity to build the new release {#sec-teamcity} + +Currently TeamCity is set to build a release at the night after it has been tagged. + +If this succeeds, the release assets are uploaded to an S3 link with the version number in the URL, as show here: + +``` +https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/v2023.07.0/ribasim_cli.zip +https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/v2023.07.0/ribasim-0.4.0-py3-none-any.whl +https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/v2023.07.0/ribasim_qgis.zip +``` + +::: {.callout-note} +A non-existent version number `v2023.07.0` is used in these links. +Replace with the version number of the new release. +Similarly the filename of the Ribasim Python wheel needs to be updated as in @sec-wheel-links. +::: + +## Do manual checks + +Our continuous integration (CI) should have caught most issues. +A current weak spot in our testing is the QGIS plugin, so it is a good idea to do some manual checks to see if it works properly. +It is a good idea to load new test models if there are any, or test any other changed functionality. + +## Generate and upload test models + +The test models are currently not automatically uploaded. +Create them locally with: + +``` +pixi run generate-testmodels +``` + +Note that this only includes the test model data, no results. +And zip the `generated_testmodels` directory to `generated_testmodels.zip`, and add these to the [release assets](https://github.com/Deltares/Ribasim/releases/latest). +Click the edit pencil icon to be able to upload it. + +## Upload artifacts from S3 to GitHub release assets + +Again edit the [release assets](https://github.com/Deltares/Ribasim/releases/latest). +Now upload the files downloaded from S3 as mentioned in @sec-teamcity. + +## Announce release + +Announce the release in appropriate channels. +Include a link to the release notes and assets, which is whatever [this](https://github.com/Deltares/Ribasim/releases/latest) resolves to at that time. +Also include a link to the [documentation](https://deltares.github.io/Ribasim/).