Skip to content

GitLab

Last edited by Bernd Flemisch
Page history

Release Manager Tasks

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)

Most Recent Release: DuMux 3.4 , 2021-08-03

Introduction

Congratulations! You've made it through the long and tough selection process and have been chosen to be the next DuMux 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 DuMux developers (LH2 employees) and organize a meeting. If possible, line this up with a DuMux Day. The following tasks should all be done and addressed during this meeting.

  • Assign developers to the major subtasks:

    • Doxygen Tasks: compile, remove warnings, check module/class descriptions.
    • Handbook Tasks: Update the Handbook & Changelog. Make sure everything is up to date.
    • Website Tasks: Make sure links are up to date.
    • DuMux-Lecture Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass.
    • DuMux-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 Tasks: Make sure everything compiles, remove all warnings, and check to see that the tests pass. Make sure the READMEs are up to date.

  • Create a group (dumux-repositories) milestone in GitLab:

    • As this release relates to multiple git projects (DuMux, DuMux-Lecture, DuMux-Course), mark the release milestone in the \dumux-repositories group. As an example, here are the milestones for DuMux 3.4, DuMux 3.3. and DuMux 3.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...).

  • 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.

  • 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.

  • Assign the open issues and MRs to the developers that are interested or qualified to address them.

  • Open a milestone issue here for release information and comments (e.g. Release Issue 3.2, or Release Issue 3.1).

  • Write an email announcement: Email an annoucement to dumux@listserv.uni-stuttgart.de, containing the following information:

    • Name / version number of the new release.
    • Link to the DuMux issue for information and comments
    • Dates of soft freeze, hard freeze, final testing, and planned release date. For examples, see here

[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 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). 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
    • 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.

  • 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 (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:

# ifndef DEF
# define DEF 2
# endif
  • Check and update parameters: Update the runtime parameter by using this script 
python3 bin/doc/getparameterlist.py

in the DuMux -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/util/create cmakelists.py script in dumux/dumux, in order to update the cmakelists in the source directory.

  • Release Branches: For each DuMux module, create a new branch titled releases/X.Y. (e.g., DuMux 3.4, DuMux-Lecture 3.4, DuMux-Course 3.4

    -Create new branch: git checkout -b releases/X.Y

    • Modify the versions required in dune.module (for example ”Version: 3.4-git” to ”Version: 3.5- 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 to test both master and the release branch with the planned configurations. Continue to check the CI for failing automatic tests.

  • Local Testing:
    -dune versions: Set up a DuMux environment with each of the dune environments DuMux 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 DuMux 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.

  • 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 DuMux root directory.

  • License: Complete the information of the copyright holders in the file LICENSE.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, where you can specify the period of interest using the mouse on the top graph. Be sure to include those who have contributed to DuMux outside of the main repository (lecture, website, and course).

  • Lecture and Course: Test or let someone else test DuMux-lecture and DuMux-course. If they build and pass without errors or warnings, mark DuMux-lecture/courses’ current git branch as compatible to the DuMux version your release. This is done by adding a tag (modify the version X.Y): Go to the gitlab tag section 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 DuMux. 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.
    • Check if DuMux runs on different machines, compilers and DUNE versions.

Releasing DuMux

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 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
    • 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

  • Zenodo citation: To cite the release, we create a doi using Zenodo, 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.

  • Write release email: Write an email to dumux@listserv.uni-stuttgart.de, include any noteworthy changes made in this release. See email examples here.

  • 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 A log of all changes applied between the different DuMux versions

  • Contribution Guidelines

  • 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: great tutorials

Mailing lists

Example emails

Past announcements of timetable and workflow: 3.2 3.1 3.0 2.11 2.10 2.9 2.8 2.7 2.5 2.4 2.3 2.1

Past announcements of the Soft Feature Freeze: 3.2 3.1 2.10 2.7

Past announcements of the Hard Feature Freeze: 3.2 2.10 2.7

Past distributions of the DuMux release candidate for testing: 3.2-rc1 3.2-rc2

Past announcements of the DuMux release 3.2 3.1 3.0 3.0-alpha 2.12 2.11 2.10 2.9 2.8 2.7 2.6 2.5 2.4 2.3 2.2 2.1