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

@@ -48,6 +48,7 @@ website:
         - contribute/core.qmd
         - contribute/python.qmd
         - contribute/addnode.qmd
+        - contribute/release.qmd
 
 format:
   html:

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.

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`
 

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:
+
+```
+<details>
+<summary>
+All changes
+</summary>
+
+# Put Github flavored markdown here
+
+</details>
+
+```
+
+## 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/).