Skip to content

Changes

Page history
Update Release Manager Tasks authored by Leon Keim's avatar Leon Keim
Hide whitespace changes
Inline Side-by-side
Release-Manager-Tasks.md
View page @ 37e9056b
# Release Manager Tasks
__Authors__: C. Grüninger (2.1), T. Fetzer (2.3), A. Kissinger (2.4), K. Weishaupt (2.9), J. Hommel (2.10), S. Ackermann (2.11), K. Heck (3.1), E. Coltman (3.2), K. Weishaupt (3.3), H. Wu (3.4), Y. Wang (3.5), M. Kelm (3.6), H. Oukili (3.7), I. Buntic (3.8)
Most Recent Release: [DuMu<sup>x</sup> 3.8](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tags/3.8.0) , 2023-11-15
## Introduction
Congratulations! You've made it through the long and tough selection process
and have been chosen to be the next DuMu<sup>x</sup> release manager. Please use this document
as a step-by-step guide through the tasks and procedures that accompany this job.
In the appendix you will find useful links, hints, and other things you may want to know about, as well
some examples of old announcement emails.
__Please update this document during your reign as release manager! Move all outdated material to the appendix.__
## [5 Weeks] prior to the release:
* __Call a meeting__: Contact all of the primary [DuMu<sup>x</sup>] developers (LH2 employees) and organize a meeting. If possible, line this up with a DuMu<sup>x</sup> Day. The following tasks should all be done and addressed during this meeting.
<br/>
* __Assign developers to the major subtasks__:
- Doxygen Tasks: compile, remove warnings, check module/class descriptions. See diff between current and prior release, see what the differences are. Mainly check for outdated docu, improve structure if possible.
- [Website] Tasks: Make sure links are up to date.
- [DuMu<sup>x</sup>-Lecture] Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass.
- [DuMu<sup>x</sup>-Course] Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass. Make sure READMEs are up to date.
- [Examples suite](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tree/master/examples) Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass. Make sure the READMEs are up to date.
<br/>
* __Create a group (dumux-repositories) milestone in GitLab:__
- As this release relates to multiple git projects ([DuMu<sup>x</sup>], [DuMu<sup>x</sup>-Lecture], [DuMu<sup>x</sup>-Course]), mark the release milestone in the \dumux-repositories group. As an example, here are the milestones for [DuMu<sup>x</sup> 3.4](https://git.iws.uni-stuttgart.de/groups/dumux-repositories/-/milestones/5), [DuMu<sup>x</sup> 3.3](https://git.iws.uni-stuttgart.de/groups/dumux-repositories/-/milestones/4). and [DuMu<sup>x</sup> 3.2](https://git.iws.uni-stuttgart.de/groups/dumux-repositories/-/milestones/2). Within this milestone, list the dates for the feature freezes, the testing, and the release, as well as the people responsible for the major subtasks (See \ref{major_subtasks}: handbook, doxygen, website...).
<br/>
* __Fix planned [Dune] and compiler compatibility:__
- Decide as a group which Dune versions and which c++ version this release will be dependent on. For example, the 3.1 release functioned with `dune-2.6` and `dune-master`, as well as c++14, but the 3.2 release was to function with `dune-2.6`, `dune-2.7`, and `dune-master`, as well as c++17. Open an issue to adapt the build-bot testing system for the release.
<br/>
* __Go through all existing Gitlab tasks ([issues] or [MRs]):__
- Review all of the existing tasks (e.g. issues and merge requests) and decide which shall be implemented and included in the next release, and which should be postponed until the next release. Mark them with the respective milestone to track the progress. If the milestone is not clear, start a discussion in gitlab to track the decision making among your peers.
<br/>
* __Assign the open [issues] and [MRs]__ to the developers that are interested or qualified to address them.
* __Open a milestone issue__ [here][issues] for release information and comments
(e.g. [Release Issue 3.2](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues/829), or
[Release Issue 3.1](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues/762)).
* __Write an email announcement:__ Email an announcement to dumux@listserv.uni-stuttgart.de, containing the following information:
- Name / version number of the new release.
- Link to the DuMu<sup>x</sup> issue for information and comments
- Dates of soft freeze, hard freeze, final testing, and planned release date. For examples, see [here](#example-emails)
<br/>
## [3 weeks] prior to the release:
* __Check remaining tasks:__
Check all open MRs and Issues for severity and impact. Make changes to the planned milestone and comment as needed.
- __CI__: Make sure the [automatic CI](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipelines) is configured to test the master with the correct dependencies. Continue to check the CI daily for failing automatic tests. If there are any failing tests or build issues, create an issue and document this in the milestone issue.
- __Edit the milestone issue:__ Update the milestone issue (e.g. [Release Issue 3.2](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues/829)). Clearly document which issues are still open, which MRs still need to be merged. This will act as a list of "announced changes". If there are open issues that need to be fixed for the release, but have not been assigned, assign them to one of the LH2 developers.
- __Announce soft feature freeze:__ This is the last opportunity to __announce__ changes to release manager, i.e. by adding a comment to the release issue in gitlab task and setting the milestone in the gitlab issue to the release. See email examples [here](#example-emails)
- __Subtask Check-in:__ Check in with the managers of the sub-tasks. Make sure anyone who needs further assistance or guidance gets it.
## [2 weeks] prior to the release:
__Hard Feature Freeze!__
* __Check remaining tasks:__ Check remaining merge requests and issues, if they only fix bugs or documentation, they can still be added or worked on. Otherwise postpone them until after the release.
* __Update the milestone issue:__ Remove all completed tasks and compile a list of issues and merge
requests that are still to be resolved. Provide links to the release branches. Make sure all of the
remaining tasks have been assigned to someone.
* __Changelog:__ Check whether the file CHANGELOG is up-to-date. You can see all commit messages since
the last release (assumed to have taken place 2019-10-11) by
```
git log --since="2019-10-11" or by
git log TAG...HEAD
```
where `TAG` is the tag of the last release (e.g. `3.4.0`)
* __Announce Freeze:__ Announce hard feature freeze. Explain how no further changes to the code,
except for bugfixes and documentation will be accepted. See email examples [here](#example-emails).
* __Install Scripts:__ Update all install scripts and the install text in the handbook. Test them according
to the text in the handbook.
* __Header check:__ Check header files by running the command `make headercheck` with with both a minimal and a maximal setup in terms of Dune dependencies. To enable the `headercheck`, turn on
`headercheck` in the [cmake.opts file](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/cmake.opts) (`DUMUX ENABLE HEADERCHECK = ON`). Look at the error message,
and include the correct headers in the failing header.
If the `headercheck` fails for a particular header `header.hh` and you want to re-execute the check only
for this header, do `HEADER=header.hh make headercheck` or `make headercheck test....hh`.
For headers that use compiler level definitions, it is necessary to include a default macro. For example
`if DEF` is defined as a compiler definition, and then called in the problem, you would need to declare
the following:
```c++
# ifndef DEF
# define DEF 2
# endif
```
* __Check and update parameters__: Update the runtime
parameter by using [this script](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/bin/doc/generate_parameterlist.py)
```
python3 bin/doc/generate_parameterlist.py
```
in the DuMu<sup>x</sup> -stable top folder. Use what the script recommends to adapt the lists as needed. If the script is broken, update it.
* __Run create_cmakelists__: Run the `bin/create_cmakelists.py` script in `dumux/dumux`, in order
to update the cmakelists in the source directory.
* __Release Branches: For each DuMu<sup>x</sup> module, create a new branch titled releases/X.Y.__ (e.g., [DuMu<sup>x</sup> 3.7](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tree/releases/3.7), [DuMu<sup>x</sup>-Lecture 3.7](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture/-/tree/releases/3.7), [DuMu<sup>x</sup>-Course 3.7](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/-/tree/releases/3.7)
-Create new branch: create protected branches using the web interface and API.
- Modify the versions required in dune.module (for example ”Version: 3.7-git” to ”Version: 3.8-
git”) and commit the change. Push the branch:
`git push origin releases/X.Y`
__From then on__, changes are still to be made to the master, but the merge commits should be
cherrypicked onto the releases/X.Y branch.
* __CI:__ Reconfigure [the CI](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipelines) to test both master and the release branch with the planned configurations. Continue to check the CI for failing automatic tests. In case you need to update or change the generated docker images, this can be done in [this file](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-docker-ci/-/blob/master/.gitlab-ci.yml). The `dumux-docker-ci` repository contains the docker files for the images and its CI builds those images as well as uploads them to the image registry. Additionally, update the [scheduled pipelines](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipeline_schedules) to test your and the previous release branch as well as the master branch (keep that). If the DuMu<sup>x</sup> pipelines should be run with other docker images, adapt [this file](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/.gitlab-ci.yml).
* __Local Testing:__
-`dune` __versions__: Set up a DuMu<sup>x</sup> environment with each of the dune environments DuMu<sup>x</sup> will
depend on (e.g. dumux=3.2 dune=2.6, 2.7, and master). In addition, set one up with the master
versions of the Dune modules so that it is ensured that the release also works with them. You
can clone the Dune modules with
```
for MOD in common geometry grid localfunctions istl;
do git clone https://gitlab.dune-project.org/core/dune-$MOD.git; done.
```
There will likely be a bunch of compiler warnings for the master version, but that is alright for the Dune-
master case.
- `dune` __modules:__ Install all Dune modules that DuMu<sup>x</sup> may depend on in each of these environments. The list of dependent
modules is documented in the dune.module file in the main folder.
- __test all versions:__ When including a new bugfix to the release, make sure to test it with all `dune` versions.
## During the week of the release:
__Final testing!__
* __Re-run tests:__ Regularly re-run `make headercheck`, `make package source`, all tests, and check the [CI daily](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipelines).
* __Update copyright:__ Check if every file has the correct and not the outdated copyright notice. You
can list files that contain the old notice with executing
```
grep -rl " Copyright " -- include =\*.{cc,hh}
```
in the DuMu<sup>x</sup> root directory.
* __License:__ Complete the information of the copyright holders in the file [AUTHORS.md](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/AUTHORS.md). To see who has contributed since the last release, you can execute
```
./bin/doc/getcontributors.sh -from 3.4.0 -to HEAD
```
in the dumux repository directory, replacing 3.4.0 by the version of the last release or its commit sha. Alternatively, you may use the graphical overview on [graph](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/network/master), where you
can specify the period of interest using the mouse on the top graph. Be sure to include those who
have contributed to DuMu<sup>x</sup> outside of the main repository (lecture, website, and course).
* __Lecture and Course:__ Test or let someone else test DuMu<sup>x</sup>-lecture and DuMu<sup>x</sup>-course. If they build and pass without errors or warnings, mark DuMu<sup>x</sup>-lecture/courses’ current git branch as compatible to the DuMu<sup>x</sup> version your release. This is done by adding a tag (modify the version X.Y): Go to the [gitlab tag section](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture/tags) and click on `+New Tag`. Here, you have to assign the tag name (e.g. 3.5.0) and enter the release branch you tested for compatibility with the current release.
* __Website:__
-Update the make handbook script. Look at commit a87e55d2793edeb8fdfe0c1115520d509f3d6775 for an example.
- Link the proper handbook version.
- Link the proper doxygen version.
- Update any changes to the installation guidelines.
* __Create a release candidate:__ Go to the tags section in DuMu<sup>x</sup>. Click create a new tab and name it after the release, with a trailing -rc1 (3.5.0-rc1, ”3.5 release candidate 1”). This tag should be set on the most recent commit from the release branch. In the message section write something like: ”The
first release candidate for the upcoming 3.5.0 release is now available. You can checkout the 3.5.0-rc1
tag via Git”.
* __Call for testing:__
- Send an email with a link to the release candidate to dumux@listserv.uni-stuttgart.de and ask for testing.
See email examples [here](#example-emails).
- Check if DuMu<sup>x</sup> runs on different machines, compilers and DUNE versions.
- Ideally, around one week should be planned for this process.
## Releasing DuMu<sup>x</sup>
__Important__ These steps are normally done together with Bernd. Make sure to schedule the time properly.
* __Protect release branches (in GitLab):__ Go to gitlab and make the [release branch](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/protected_branches) protected. Select the release branch to protect. In the ”allowed to merge” column, select maintainers. In the
allowed to push column, select no one, then press select. This means that the branch can only be
modified via a merge request merged by a maintainer.
* __Create new tags:__
- Go to the [gitlab tag section](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/tags)
- The release tags should have a tailing 0 (for example 3.5.0) for listing purposes.
- Click on `+New Tag`. Here, you have to assign the tag name (e.g. 3.5.0) and enter the commit-id
of the last commit for the current release.
- Repeat the same procedure for dumux-lecture and the dumux-course
* __DaRUS citation:__ To cite the release, we create a doi using [DaRUS](https://darus.uni-stuttgart.de/dataset.xhtml?persistentId=doi:10.18419/darus-3405), and a tarball of the software.
Bernd has the account details and can help you with this. It would be helpful to prepare a list of those
who should be included in the citation as authors beforehand. Some helpful tips:
- Make sure that your release branch is available at [softwareheritage](https://archive.softwareheritage.org/browse/snapshot/50fb10d5d33803233d6475cf1fab33b088c8a143/releases/?origin_url=https://github.com/dumux/dumux)
- If it is not, click on `save again` on the [code page of softwareheritage](https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://github.com/dumux/dumux&snapshot=50fb10d5d33803233d6475cf1fab33b088c8a143)
- Upload a tar.gz file of the DuMux release to DaRUS
- In general, follow the structure of the [DaRUS entry for release e.g. 3.7](https://darus.uni-stuttgart.de/dataset.xhtml?persistentId=doi:10.18419/darus-3405)
- text formatting in DaRUS is done via html syntax
* __Updating badges:__ Update the `archived` badge in the dumux repository. You can access and change the badges in the browser using gitLab: "Settings->General->Badges". The necessary information for the `archived` badge can be found when clicking on your release in the [softwareheritage dumux releases](https://archive.softwareheritage.org/browse/snapshot/50fb10d5d33803233d6475cf1fab33b088c8a143/releases/?origin_url=https://github.com/dumux/dumux). On the right side of the screen (at the time of writing this), you will find a button `Permalink` with SoftWare Heritage persistent IDentifiers (SWHIDs) as well as links to the images of the badges (Copy image link).
* __New release entry__: Prepare are a new entry for your release in the dumux [releases page](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/releases).
* __Write release email:__ Write an email to dumux@listserv.uni-stuttgart.de, include any noteworthy
changes made in this release. See email examples [here](#example-emails).
* __Congratulations!__ Now enjoy the celebration and be happy and proud. Make sure to invite your
colleagues too.
## After the release
* Bump version in dune.module to next version with trailing -git on master, and open a new section
in the changelog.
* Email the dumux mailing list with updates about things that are to be supported, or things that will
no longer be supported in the next release (different dune versions, compilers, etc.)
## Appendix
__Useful files__ It may be useful to know about the following files and folders.
* [__Changelog__](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md) A log of all changes applied between the different DuMu<sup>x</sup> versions
* [Contribution Guidelines](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CONTRIBUTING.md)
* __Documentation: Doxygen:__ files needed for handbook and doxygen
* __Documentation: Handbook:__ For handbook generation.
__Useful web sites__
The following web sites are also helpful, just browse through them as far as you need.
* [git](https://www.atlassian.com/git/tutorials): great tutorials
__Mailing lists__
* dumux@listserv.uni-stuttgart.de
- a list of DuMu<sup>x</sup> developers and users
- subscribe https://listserv.uni-stuttgart.de/mailman/listinfo/dumux
- archive of old mails http://www.mail-archive.com/dumux@listserv.uni-stuttgart.de/
* dumux_lh2@listserv.uni-stuttgart.de
- a list of all users at the department
- subscribe https://listserv.uni-stuttgart.de/mailman/listinfo/dumux_lh2
* dumux-commits@listserv.uni-stuttgart.de
- automatically generates a mail for each DuMux commit
- do not send an email to this list
- subscribe https://listserv.uni-stuttgart.de/mailman/listinfo/dumux-commits
## Example emails
__Past announcements of timetable and workflow:__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q1/002442.html)
[3.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2019q3/002367.html)
[3.0](https://listserv.uni-stuttgart.de/pipermail/dumux/2018q4/002070.html)
[2.11](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q1/001724.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001653.html)
[2.9](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q1/001542.html)
[2.8](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q3/001231.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q1/001101.html)
[2.5](https://listserv.uni-stuttgart.de/pipermail/dumux/2014q1/000746.html)
[2.4](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q3/000606.html)
[2.3](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q1/000415.html)
[2.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2012q1/000010.html)
__Past announcements of the Soft Feature Freeze:__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002488.html)
[3.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2019q3/002368.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001660.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q1/001103.html)
__Past announcements of the Hard Feature Freeze:__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002502.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001676.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q1/001121.html)
__Past distributions of the DuMu<sup>x</sup> release candidate for testing:__
[3.2-rc1](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002514.html)
[3.2-rc2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002517.html)
__Past announcements of the DuMu<sup>x</sup> release__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002521.html)
[3.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2019q4/002377.html)
[3.0](https://listserv.uni-stuttgart.de/pipermail/dumux/2018q4/002140.html)
[3.0-alpha](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q4/001801.html)
[2.12](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q4/001800.html)
[2.11](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q1/001729.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001683.html)
[2.9](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q1/001566.html)
[2.8](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q3/001339.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q2/001126.html)
[2.6](https://listserv.uni-stuttgart.de/pipermail/dumux/2014q4/000917.html)
[2.5](https://listserv.uni-stuttgart.de/pipermail/dumux/2014q2/000788.html)
[2.4](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q4/000621.html)
[2.3](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q1/000466.html)
[2.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2012q4/000344.html)
[2.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2012q1/000153.html)
[Website]: https://dumux.org/
[Dune]: https://www.dune-project.org/
[DuMu<sup>x</sup>]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux
[DuMu<sup>x</sup>-Lecture]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture
[DuMu<sup>x</sup>-Course]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course
[issues]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/issues
[MRs]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/merge_requests
# Release Manager Tasks
__Authors__: C. Grüninger (2.1), T. Fetzer (2.3), A. Kissinger (2.4), K. Weishaupt (2.9), J. Hommel (2.10), S. Ackermann (2.11), K. Heck (3.1), E. Coltman (3.2), K. Weishaupt (3.3), H. Wu (3.4), Y. Wang (3.5), M. Kelm (3.6), H. Oukili (3.7), I. Buntic (3.8), L. Keim (3.9)
Most Recent Release: [DuMu<sup>x</sup> 3.9](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tags/3.9.0) , 2024-07-09
## Introduction
Congratulations! You've made it through the long and tough selection process
and have been chosen to be the next DuMu<sup>x</sup> release manager. Please use this document
as a step-by-step guide through the tasks and procedures that accompany this job.
In the appendix you will find useful links, hints, and other things you may want to know about, as well
some examples of old announcement emails.
__Please update this document during your reign as release manager! Move all outdated material to the appendix.__
## [5 Weeks] prior to the release:
* __Call a meeting__: Contact all of the primary [DuMu<sup>x</sup>] developers (LH2 employees) and organize a meeting. If possible, line this up with a DuMu<sup>x</sup> Day. The following tasks should all be done and addressed during this meeting.
<br/>
* __Assign developers to the major subtasks__:
- Doxygen Tasks: compile, remove warnings, check module/class descriptions. See diff between current and prior release, see what the differences are. Mainly check for outdated docu, improve structure if possible.
- [Website] Tasks: Make sure links are up to date.
- [DuMu<sup>x</sup>-Lecture] Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass.
- [DuMu<sup>x</sup>-Course] Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass. Make sure READMEs are up to date.
- [Examples suite](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tree/master/examples) Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass. Make sure the READMEs are up to date.
<br/>
* __Create a group (dumux-repositories) milestone in GitLab:__
- As this release relates to multiple git projects ([DuMu<sup>x</sup>], [DuMu<sup>x</sup>-Lecture], [DuMu<sup>x</sup>-Course]), mark the release milestone in the \dumux-repositories group. As an example, here are the milestones for [DuMu<sup>x</sup> 3.4](https://git.iws.uni-stuttgart.de/groups/dumux-repositories/-/milestones/5), [DuMu<sup>x</sup> 3.3](https://git.iws.uni-stuttgart.de/groups/dumux-repositories/-/milestones/4). and [DuMu<sup>x</sup> 3.2](https://git.iws.uni-stuttgart.de/groups/dumux-repositories/-/milestones/2). Within this milestone, list the dates for the feature freezes, the testing, and the release, as well as the people responsible for the major subtasks (See \ref{major_subtasks}: handbook, doxygen, website...).
<br/>
* __Fix planned [Dune] and compiler compatibility:__
- Decide as a group which Dune versions and which c++ version this release will be dependent on. For example, the 3.1 release functioned with `dune-2.6` and `dune-master`, as well as c++14, but the 3.2 release was to function with `dune-2.6`, `dune-2.7`, and `dune-master`, as well as c++17. Open an issue to adapt the build-bot testing system for the release.
<br/>
* __Go through all existing Gitlab tasks ([issues] or [MRs]):__
- Review all of the existing tasks (e.g. issues and merge requests) and decide which shall be implemented and included in the next release, and which should be postponed until the next release. Mark them with the respective milestone to track the progress. If the milestone is not clear, start a discussion in gitlab to track the decision making among your peers.
<br/>
* __Assign the open [issues] and [MRs]__ to the developers that are interested or qualified to address them.
* __Open a milestone issue__ [here][issues] for release information and comments
(e.g. [Release Issue 3.2](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues/829), or
[Release Issue 3.1](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues/762)).
* __Write an email announcement:__ Email an announcement to dumux@listserv.uni-stuttgart.de, containing the following information:
- Name / version number of the new release.
- Link to the DuMu<sup>x</sup> issue for information and comments
- Dates of soft freeze, hard freeze, final testing, and planned release date. For examples, see [here](#example-emails)
<br/>
## [3 weeks] prior to the release:
* __Check remaining tasks:__
Check all open MRs and Issues for severity and impact. Make changes to the planned milestone and comment as needed.
- __CI__: Make sure the [automatic CI](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipelines) is configured to test the master with the correct dependencies. Continue to check the CI daily for failing automatic tests. If there are any failing tests or build issues, create an issue and document this in the milestone issue.
- __Edit the milestone issue:__ Update the milestone issue (e.g. [Release Issue 3.2](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues/829)). Clearly document which issues are still open, which MRs still need to be merged. This will act as a list of "announced changes". If there are open issues that need to be fixed for the release, but have not been assigned, assign them to one of the LH2 developers.
- __Announce soft feature freeze:__ This is the last opportunity to __announce__ changes to release manager, i.e. by adding a comment to the release issue in gitlab task and setting the milestone in the gitlab issue to the release. See email examples [here](#example-emails)
- __Subtask Check-in:__ Check in with the managers of the sub-tasks. Make sure anyone who needs further assistance or guidance gets it.
## [2 weeks] prior to the release:
__Hard Feature Freeze!__
* __Check remaining tasks:__ Check remaining merge requests and issues, if they only fix bugs or documentation, they can still be added or worked on. Otherwise postpone them until after the release.
* __Update the milestone issue:__ Remove all completed tasks and compile a list of issues and merge
requests that are still to be resolved. Provide links to the release branches. Make sure all of the
remaining tasks have been assigned to someone.
* __Changelog:__ Check whether the file CHANGELOG is up-to-date. You can see all commit messages since
the last release (assumed to have taken place 2019-10-11) by
```
git log --since="2019-10-11" or by
git log TAG...HEAD
```
where `TAG` is the tag of the last release (e.g. `3.4.0`)
* __Announce Freeze:__ Announce hard feature freeze. Explain how no further changes to the code,
except for bugfixes and documentation will be accepted. See email examples [here](#example-emails).
* __Install Scripts:__ Update all install scripts and the install text in the handbook. Test them according
to the text in the handbook.
* __Header check:__ Check header files by running the command `make headercheck` with with both a minimal and a maximal setup in terms of Dune dependencies. To enable the `headercheck`, turn on
`headercheck` in the [cmake.opts file](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/cmake.opts) (`DUMUX ENABLE HEADERCHECK = ON`). Look at the error message,
and include the correct headers in the failing header.
If the `headercheck` fails for a particular header `header.hh` and you want to re-execute the check only
for this header, do `HEADER=header.hh make headercheck` or `make headercheck test....hh`.
For headers that use compiler level definitions, it is necessary to include a default macro. For example
`if DEF` is defined as a compiler definition, and then called in the problem, you would need to declare
the following:
```c++
# ifndef DEF
# define DEF 2
# endif
```
* __Check and update parameters__: Update the runtime
parameter by using [this script](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/bin/doc/generate_parameterlist.py)
```
python3 bin/doc/generate_parameterlist.py
```
in the DuMu<sup>x</sup> -stable top folder. Use what the script recommends to adapt the lists as needed. If the script is broken, update it.
* __Run create_cmakelists__: Run the `bin/create_cmakelists.py` script in `dumux/dumux`, in order
to update the cmakelists in the source directory.
* __Release Branches: For each DuMu<sup>x</sup> module, create a new branch titled releases/X.Y.__ (e.g., [DuMu<sup>x</sup> 3.7](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tree/releases/3.7), [DuMu<sup>x</sup>-Lecture 3.7](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture/-/tree/releases/3.7), [DuMu<sup>x</sup>-Course 3.7](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/-/tree/releases/3.7)
-Create new branch: create protected branches using the web interface and API.
- Modify the versions required in dune.module (for example ”Version: 3.7-git” to ”Version: 3.8-
git”) and commit the change. Push the branch:
`git push origin releases/X.Y`
__From then on__, changes are still to be made to the master, but the merge commits should be
cherrypicked onto the releases/X.Y branch.
* __CI:__ Reconfigure [the CI](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipelines) to test both master and the release branch with the planned configurations. Continue to check the CI for failing automatic tests. In case you need to update or change the generated docker images, this can be done in [this file](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-docker-ci/-/blob/master/.gitlab-ci.yml). The `dumux-docker-ci` repository contains the docker files for the images and its CI builds those images as well as uploads them to the image registry. Additionally, update the [scheduled pipelines](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipeline_schedules) to test your and the previous release branch as well as the master branch (keep that). If the DuMu<sup>x</sup> pipelines should be run with other docker images, adapt [this file](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/.gitlab-ci.yml).
* __Local Testing:__
-`dune` __versions__: Set up a DuMu<sup>x</sup> environment with each of the dune environments DuMu<sup>x</sup> will
depend on (e.g. dumux=3.2 dune=2.6, 2.7, and master). In addition, set one up with the master
versions of the Dune modules so that it is ensured that the release also works with them. You
can clone the Dune modules with
```
for MOD in common geometry grid localfunctions istl;
do git clone https://gitlab.dune-project.org/core/dune-$MOD.git; done.
```
There will likely be a bunch of compiler warnings for the master version, but that is alright for the Dune-
master case.
- `dune` __modules:__ Install all Dune modules that DuMu<sup>x</sup> may depend on in each of these environments. The list of dependent
modules is documented in the dune.module file in the main folder.
- __test all versions:__ When including a new bugfix to the release, make sure to test it with all `dune` versions.
## During the week of the release:
__Final testing!__
* __Re-run tests:__ Regularly re-run `make headercheck`, `make package source`, all tests, and check the [CI daily](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/pipelines).
* __Update copyright:__ Check if every file has the correct and not the outdated copyright notice. You
can list files that contain the old notice with executing
```
grep -rl " Copyright " -- include =\*.{cc,hh}
```
in the DuMu<sup>x</sup> root directory.
* __License:__ Complete the information of the copyright holders in the file [AUTHORS.md](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/AUTHORS.md). To see who has contributed since the last release, you can execute
```
./bin/doc/getcontributors.sh -from 3.4.0 -to HEAD
```
in the dumux repository directory, replacing 3.4.0 by the version of the last release or its commit sha. Alternatively, you may use the graphical overview on [graph](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/network/master), where you
can specify the period of interest using the mouse on the top graph. Be sure to include those who
have contributed to DuMu<sup>x</sup> outside of the main repository (lecture, website, and course).
* __Lecture and Course:__ Test or let someone else test DuMu<sup>x</sup>-lecture and DuMu<sup>x</sup>-course. If they build and pass without errors or warnings, mark DuMu<sup>x</sup>-lecture/courses’ current git branch as compatible to the DuMu<sup>x</sup> version your release. This is done by adding a tag (modify the version X.Y): Go to the [gitlab tag section](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture/tags) and click on `+New Tag`. Here, you have to assign the tag name (e.g. 3.5.0) and enter the release branch you tested for compatibility with the current release.
* __Website:__
-Update the make handbook script. Look at commit a87e55d2793edeb8fdfe0c1115520d509f3d6775 for an example.
- Link the proper handbook version.
- Link the proper doxygen version.
- Update any changes to the installation guidelines.
* __Create a release candidate:__ Go to the tags section in DuMu<sup>x</sup>. Click create a new tab and name it after the release, with a trailing -rc1 (3.5.0-rc1, ”3.5 release candidate 1”). This tag should be set on the most recent commit from the release branch. In the message section write something like: ”The
first release candidate for the upcoming 3.5.0 release is now available. You can checkout the 3.5.0-rc1
tag via Git”.
* __Call for testing:__
- Send an email with a link to the release candidate to dumux@listserv.uni-stuttgart.de and ask for testing.
See email examples [here](#example-emails).
- Check if DuMu<sup>x</sup> runs on different machines, compilers and DUNE versions.
- Ideally, around one week should be planned for this process.
## Releasing DuMu<sup>x</sup>
__Important__ These steps are normally done together with Bernd. Make sure to schedule the time properly.
* __Protect release branches (in GitLab):__ Go to gitlab and make the [release branch](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/protected_branches) protected. Select the release branch to protect. In the ”allowed to merge” column, select maintainers. In the
allowed to push column, select no one, then press select. This means that the branch can only be
modified via a merge request merged by a maintainer.
* __Create new tags:__
- Go to the [gitlab tag section](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/tags)
- The release tags should have a tailing 0 (for example 3.5.0) for listing purposes.
- Click on `+New Tag`. Here, you have to assign the tag name (e.g. 3.5.0) and enter the commit-id
of the last commit for the current release.
- Repeat the same procedure for dumux-lecture and the dumux-course
* __DaRUS citation:__ To cite the release, we create a doi using [DaRUS](https://darus.uni-stuttgart.de/dataset.xhtml?persistentId=doi:10.18419/darus-3405), and a tarball of the software.
Bernd has the account details and can help you with this. It would be helpful to prepare a list of those
who should be included in the citation as authors beforehand. Some helpful tips:
- Make sure that your release branch is available at [softwareheritage](https://archive.softwareheritage.org/browse/snapshot/50fb10d5d33803233d6475cf1fab33b088c8a143/releases/?origin_url=https://github.com/dumux/dumux)
- If it is not, click on `save again` on the [code page of softwareheritage](https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://github.com/dumux/dumux&snapshot=50fb10d5d33803233d6475cf1fab33b088c8a143)
- Upload a tar.gz file of the DuMux release to DaRUS
- In general, follow the structure of the [DaRUS entry for release e.g. 3.7](https://darus.uni-stuttgart.de/dataset.xhtml?persistentId=doi:10.18419/darus-3405)
- text formatting in DaRUS is done via html syntax
* __Updating badges:__ Update the `archived` badge in the dumux repository. You can access and change the badges in the browser using gitLab: "Settings->General->Badges". The necessary information for the `archived` badge can be found when clicking on your release in the [softwareheritage dumux releases](https://archive.softwareheritage.org/browse/snapshot/50fb10d5d33803233d6475cf1fab33b088c8a143/releases/?origin_url=https://github.com/dumux/dumux). On the right side of the screen (at the time of writing this), you will find a button `Permalink` with SoftWare Heritage persistent IDentifiers (SWHIDs) as well as links to the images of the badges (Copy image link).
* __New release entry__: Prepare are a new entry for your release in the dumux [releases page](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/releases).
* __Write release email:__ Write an email to dumux@listserv.uni-stuttgart.de, include any noteworthy
changes made in this release. See email examples [here](#example-emails).
* __Congratulations!__ Now enjoy the celebration and be happy and proud. Make sure to invite your
colleagues too.
## After the release
* Bump version in dune.module to next version with trailing -git on master, and open a new section
in the changelog.
* Email the dumux mailing list with updates about things that are to be supported, or things that will
no longer be supported in the next release (different dune versions, compilers, etc.)
## Appendix
__Useful files__ It may be useful to know about the following files and folders.
* [__Changelog__](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md) A log of all changes applied between the different DuMu<sup>x</sup> versions
* [Contribution Guidelines](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CONTRIBUTING.md)
* __Documentation: Doxygen:__ files needed for handbook and doxygen
* __Documentation: Handbook:__ For handbook generation.
__Useful web sites__
The following web sites are also helpful, just browse through them as far as you need.
* [git](https://www.atlassian.com/git/tutorials): great tutorials
__Mailing lists__
* dumux@listserv.uni-stuttgart.de
- a list of DuMu<sup>x</sup> developers and users
- subscribe https://listserv.uni-stuttgart.de/mailman/listinfo/dumux
- archive of old mails http://www.mail-archive.com/dumux@listserv.uni-stuttgart.de/
* dumux_lh2@listserv.uni-stuttgart.de
- a list of all users at the department
- subscribe https://listserv.uni-stuttgart.de/mailman/listinfo/dumux_lh2
* dumux-commits@listserv.uni-stuttgart.de
- automatically generates a mail for each DuMux commit
- do not send an email to this list
- subscribe https://listserv.uni-stuttgart.de/mailman/listinfo/dumux-commits
## Example emails
__Past announcements of timetable and workflow:__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q1/002442.html)
[3.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2019q3/002367.html)
[3.0](https://listserv.uni-stuttgart.de/pipermail/dumux/2018q4/002070.html)
[2.11](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q1/001724.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001653.html)
[2.9](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q1/001542.html)
[2.8](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q3/001231.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q1/001101.html)
[2.5](https://listserv.uni-stuttgart.de/pipermail/dumux/2014q1/000746.html)
[2.4](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q3/000606.html)
[2.3](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q1/000415.html)
[2.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2012q1/000010.html)
__Past announcements of the Soft Feature Freeze:__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002488.html)
[3.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2019q3/002368.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001660.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q1/001103.html)
__Past announcements of the Hard Feature Freeze:__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002502.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001676.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q1/001121.html)
__Past distributions of the DuMu<sup>x</sup> release candidate for testing:__
[3.2-rc1](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002514.html)
[3.2-rc2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002517.html)
__Past announcements of the DuMu<sup>x</sup> release__
[3.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2020q2/002521.html)
[3.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2019q4/002377.html)
[3.0](https://listserv.uni-stuttgart.de/pipermail/dumux/2018q4/002140.html)
[3.0-alpha](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q4/001801.html)
[2.12](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q4/001800.html)
[2.11](https://listserv.uni-stuttgart.de/pipermail/dumux/2017q1/001729.html)
[2.10](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q3/001683.html)
[2.9](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q1/001566.html)
[2.8](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q3/001339.html)
[2.7](https://listserv.uni-stuttgart.de/pipermail/dumux/2015q2/001126.html)
[2.6](https://listserv.uni-stuttgart.de/pipermail/dumux/2014q4/000917.html)
[2.5](https://listserv.uni-stuttgart.de/pipermail/dumux/2014q2/000788.html)
[2.4](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q4/000621.html)
[2.3](https://listserv.uni-stuttgart.de/pipermail/dumux/2013q1/000466.html)
[2.2](https://listserv.uni-stuttgart.de/pipermail/dumux/2012q4/000344.html)
[2.1](https://listserv.uni-stuttgart.de/pipermail/dumux/2012q1/000153.html)
[Website]: https://dumux.org/
[Dune]: https://www.dune-project.org/
[DuMu<sup>x</sup>]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux
[DuMu<sup>x</sup>-Lecture]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture
[DuMu<sup>x</sup>-Course]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course
[issues]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/issues
[MRs]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/merge_requests