- Generated by
1.11.0
|
HPCW 3.0
|
This file aims at clarifying expectations from the developers for their contributions to be accepted.
At the time of writing, the only coding policy applies to the headers. Nevertheless, we strongly promote KISS principle.
The source files are expected to exhibit license headers, along with author names. This is verified automatically by the CI, at the first stage of the pipeline. The format of the headers must follow this format:
For instance:
This format is enforced by the Python package license-tools, which is called by the pre-commit hook (see developers environment below). The configuration for the HPCW repository is available here. At the time of writing, it only enforces the policy for the CMake files (*.cmake, as well as CMakeList.txt).
DKRZ kindly offers resources from the Levante HPC-system for running the HPCW tests. Leveraging GitLab CI, every push in the context of a merge request undergoes several steps, from syntactic checks to numerical deviation tests of the projects. However, the majority of the CI can only be started by certain project members. Therefore it is recommended to assign a reviewer from one of the owners/maintainers (found here) to a merge request.
The various tests mainly consist of:
Every error detected is reported to the committer, as well as in the GitLab related merge request. This helps ensure that every commit is safe for the whole project. If you struggle with an error, open an issue on GitLab.
Most of the tests run automatically on creation of a merge request and subsequent pushes to an existing merge request. There is an exception for some larger test cases that need to be started manually. They have been excluded from automatic execution due to their resource demands. If you want to execute them in the context of a merge request, you have to navigate to the corresponding pipeline and manually enable them. Furthermore, all tests are executed on pushes to the main branch. In this instance, the larger test cases are also executed automatically without the need for further intervention. The icon-LAM test case is the only exception. The associated CI jobs are entirely manual and should only be executed after significant changes to ICON due to their resource demand.
To maximize the success rate of the continuous integration steps, developers should set up their environment following the steps below:
re.Pattern, which comes with Python 3.7 :warning:user.name setting is properly set in git (e.g., read this https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git)python3 -m pip install --user --upgrade pre-commit)pre-commit install to install the git pre-commit hook;pre-commit run to install hook dependencies, namely license-tools at the time of writing :warning: requires internet.Then, in order to run the pre-commit hook, simply run pre-commit run --all-files --verbose --color always from the root of the HPCW repository. This will also be called every time you run a git commit.
Various tools exist to mimic the behavior of the CI pipeline locally, for instance running the official GitLab runner or using third party tools like gitlab-ci-local.
However, we do not recommend to use such tools for the whole pipeline: their configuration can be tedious, and above all, testing the large cases of some models requires several nodes of high-end machines, that will most likely make your workstation run out of memory.
From v3.0 onwards, the changelog for HPCW is generated from git notes that are attached to commits. The changelog generator inspects notes in three different namespaces:
changelogs/changeschangelogs/fixchangelogs/newIf you want the changes from your merge request to be reflected in the changelog of HPCW, attach a note to any of the commits to be merged by executing one of the following commands:
git notes --ref=changelogs/changes edit [-m "...."]git notes --ref=changelogs/fix edit [-m "...."]git notes --ref=changelogs/new edit [-m "...."]By default, these commands add a note to the current HEAD, in the namespace specified in the --ref option. The CI for HPCW includes a step that checks the commits in your merge request and informs you if there are currently no notes in any of the relevant namespaces. This reminder may be ignored if the changes in the merge request do not need to be reflected in the changelog (for example, we do not need multiple entries in the changelog for typo fixes in the documentation).
Much like tags, notes are not pushed by default. In order to push the notes, execute the following command:
Similarly, if you want to fetch the remote notes, execute:
If you want to rebase and amend certain commits, be aware that by default, git will overwrite any notes attached to the amended commits. You can configure git to rewrite any existing notes by adding the following lines to your .git/config:
1.11.0