Common Community Physics Package (CCPP)

Workflow for development and releases

Github allows for cloning and forking of Git repositories, and the forking workflow will be used for the CCPP development. More information may be found at: https://www.atlassian.com/git/tutorials/comparing-workflows#forking-workflow. While this tutorial is supplied by the Atlassian vendor, it is directly relevant to development in Github.

In practice, each developer will work on their own fork of the repository and clone from that work for editing code. Each developer can push to their own fork freely (it is recommended to push often). Developers issue a pull request when contributions are ready to be merged in the central repository. It is possible for developers to pull branches from each other's repositories and collaborate on a common feature.

In the collaborative context of a unified software development team, an advantage of the forking approach is that it can be used in a recursive manner. After the central repository is established, each partner can create a fork, preferably with automatic syncing. Within each partner organization, each developer then forks their organization's fork as their central repository. For large partner organizations, it is even possible to add another level by team, group or division.

A common concern for operational codes is code integrity. In the proposed model, operational users will have their own fork. For compiling the code for operations, a clone of that repository is created on a local disk. If the fork and clone are synced manually the operational code will remain safe and unchanged until the operational user actively pulls new changes. Even if synced automatically, operational users can add their own tag or use a specific commit to prevent accidental changes. The operational clones can be located inside firewalls and on backed-up disks as required by operational guidelines.

Staying in control: reviewing code

The previous paragraph explains the role of several types of branches and forks. We now discuss procedures to control the contents of the master and develop branches. This is the role of the review process.

The functionality offered by GitHub hosting services (issue tracking, code review, pull requests, and automated enforcement of license agreements) will be used to increase the efficiency and reliability of the review process. The merging of branches should happen through a pull request within the GitHub environment. Each pull request will be assigned reviewers and the review should happen within the GitHub environment. Discussions and comments will be stored within the system and can be referred to later if needed. This is different from older common working practices where reviews happened by email and were almost impossible to trace later on.

It is in the interest of both developers and reviewers to review and merge code often in small incremental changes rather than massive changes at once. This facilitates the process, exposes code earlier to other developers who could be affected and facilitates the merging. Once code has been reviewed and accepted in the review mechanism, it is merged as is without further modifications, clean-up or other improvements. Because the developers should have merged their branch up to the current level of the develop branch, the merge will be automatic and without conflict.

Testing

Testing is a mandatory step of the development process and no branch will be merged without prior testing. IPDe already has a unit test in its repository.

The parameterizations within the CCPP will have a test suite covering a variety of levels, from unit tests to more complex interactions. In addition, every developer is expected to provide a new test specific to their major development. The tests should be reviewed as any other part of the system and any by-passing or relaxing of a test criterion should be fully justified and documented.

Although tests will run automatically, triggered by a commit to the master branch, developers can run them manually at any time on their branch. They will be encouraged to do this regularly to detect potential problems early and fix them early.


UCAR | Privacy Policy | Terms of Use