CABLE code management

Claire Carouge

Several versions exist with different science.

Hard to bring all the science together.

Hard to know what is in each version.

No minimum quality standard is required.

Hard to track who has done what and for why.

Documentation is not updated so it's hard to know how to use CABLE.

It isn't the first time we try.

Let's see how we propose to do it.

Our Goal

Provide essential tools for successful collaborative code:

• continuous integration
• authorship is kept throughout
• enables easy connections between issues, commits and code reviews
• collaborative by design, no permission issues
• integration with modern editors for visual version control

Model development happens in branches

Nobody can write directly to the main branch. All other branches are open to everyone

This ensures all changes go through the same quality control steps.

All new development should be protected by a namelist option:

• new option
• new value for an existing option

Contributions will need to pass automated tests:

compilation, coding standards compliance, documentation formatting, etc.

Standardised scientific evaluation required:

providing benchcab's results will be required

All changes will be accepted, not a yes/no criteria

Tests will evolve to ensure they stay relevant

Open a PR after the first commit.

All communication about the implementation goes in the PR. It provides:

• public communication
• connected to the code
• recorded communication linked to the feature

Update the PR description as you develop the code

A PR template will be provided to identify the necessary information

Integrate your changes in the main version often

Integrate changes from main version even more often

Git and GitHub simplify merging both ways and conflict resolution.

Merging small changes often is faster than merging large changes rarely.

Allows others to consider your developments in their work.

New developer_only option to safeguard users against using scientifically non-safe options

All code contributions will be reviewed

When you write a document, you ask people to give feedback to improve it. The same applies to code.

Authors will need to be responsive during the review period.

Release notes inform the exact content of each version

Identification of authors in release notes

Suggestion of co-authorship when using newly released features

Version numbers and DOI for easy reference and access

Fast accessibility of new features to promote collaboration

All code contributions must include the required documentation changes.

The documentation is accessible: it lives with and within the source code.

The review will apply to the documentation as well.

Work to update the documentation is underway

Build and maintain a collection of configurations for CABLE.

Separate source code, run scripts and inputs

Maintain compiled executables of released versions on supported platforms

Refer to the Developer's Guide in the documentation for details on:

• roles and responsibilities
• guidelines and processes
• coding standards