Release workflow

Release procedure for ComIn releases:

The main branch contains all recent changes, ie. it is "unstable"
When a new release is upcoming, a release branch comin-X.Y is created.
Right after the creation of the release branch, the version number in the main branch is increased
New features do not enter this release branch. Only bug fixes (patches) are allowed to be added to the comin-X.Y branch.
A release is published then as a tag comin-X.Y.Z (including the patch level)
as a policy, no feature backports are provided. Bug fixes (patches) are applied only to the current release and to the release which is currently used by the current ICON version.

    gitGraph
       checkout main
       commit id: "start"
      branch comin-1.0
      commit type: HIGHLIGHT tag: "comin-1.0.0"
      commit
       checkout main
      commit
      checkout comin-1.0
      commit type: HIGHLIGHT tag: "comin-1.0.1"
      commit
      commit
      commit type: HIGHLIGHT tag: "comin-1.0.2"
       checkout main
      commit
      commit
      branch comin-1.1
      commit type: HIGHLIGHT tag: "comin-1.1.0"
      commit
      commit type: HIGHLIGHT tag: "comin-1.1.1"
       checkout main
      commit
      commit

The releases are created automatically by GitLab CI if a commit with a tag of the form comin-x.y.z is created. Please ensure that the commit met the following conditions:

The version number in the CMakeLists.txt must match the version number of the commit.
The commit must be contained in the branch comin-x.y

Updating the test references

The testing uses reference files that are compared with the terminal output of the tests. In some situations changes in the reference files are unavoidable or new references need to be generated for new tests. This can be done as follows:

Configure ComIn with ENABLE_TESTING=ON
Build it with make
Run the tests: ctest. Some tests might fail due to the mismatch with the reference.
Run make update_references. This copies all references from the tests into the ComIn repository.
Check the changes carefully. E.g. using git diff.
Add the updated reference files to the repository and create a commit.

Note: To run all tests ComIn have to be configured with yaxt and yac.

Updating the replay data

The replay data can be updated semi-automatically. The following steps need to be executed:

create a feature branch in ComIn (and push if to the Gitlab repository)
create a feature branch in ICON referencing the ComIn feature branch (and push it to a Gitlab repository)
run the CI pipeline manually (Build->Pipelines->Run pipeline)
- set the variable ICON_BRANCH to the name of the icon feature branch.
- set the variable ICON_REPO to the ssh url for cloning the ICON repository. (default: git@gitlab.dkrz.de:icon/icon.git)
Run the pipeline
- The job generate_replay_data will create an artifact predef_replay_data.cmake
- download the file and replace it in the comin repository (cmake/Scripts subdirectory)

Pre-commit hooks

Pre-commit hooks are tests that run every time you try to commit. A very basic test is to check for lines containing trailing whitespace, or to apply the fprettify auto-formatter for modern Fortran code.

Running pre-commit hooks locally

You will need to have the pre-commit package manager installed, see https://pre-commit.com for instructions. The next time you run git commit, the hooks listed in .pre-commit-config.yaml will be executed.

Gitlab CI/CD pipeline

Whenever changes are pushed to the GitLab server, the CI/CD pipeline also runs the pre-commit hook scripts. The intention here is to catch formatting problems while they are in a feature branch. They would need to be fixed before merging into the main branch.

Contributing guidelines

We, the ComIn team, don't formulate a set of hard rules but instead agree on guidelines for how we want to organize development of ComIn. The guidelines are given below, roughly organized by development stage. In case updates or corrections are required, please open an issue and tag b309183. Further information on the ComIn team and the development process can be found in the "Memorandum of Understanding" as part of the ICON docs.

Branches and issues

Bigger change sets should always be documented in an issue in addition to the related branch and merge request. Smaller changes and bug fixes can be handled by branch and merge request alone.
Issues should be labelled (Gitlab labels) with a topic label (e.g. GPU, Documentation, CI/CD) to improve findability. In addition, a milestone should be set (Gitlab property "Milestone") and also indicated by a label (e.g. Release 0.5.0). This supports the regular progress review.
Issues which include changes in the API need to be labelled as "API change".
If the topic of an issue changes through the discussion, it should be closed and a new one opened to prevent changing issue names.

Merge requests (MR)

Change sets that introduce larger changes, i.e. if they result in a change of the API, should be communicated as early as possible.
MR that are not just bug fixes should, once completed, remain open for a few days if agreement by all partners has not been otherwise indicated. However, early communication is the preferred approach.
For larger number of commits (e.g. >5 for small change sets) squash commits are preferred.
Developers should not merge their own MRs.
The CI pipeline checks for an update to the CHANGELOG.md with every MR. Please document your code changes briefly. In case of no or very minor code changes it is possible to circumvent the pipeline check by adding a NO CHANGELOG label to the MR.

General development

To avoid buildup of technical debt, an issue on improving the legacy implementation should be opened when encountering debt during the development.
Issues are grouped by the release they are intended to be included for (this happens via milestone labels). This grouping is reviewed regularly at the larger meetings.

Table of Contents