CableDeveloperGuide

This document describes the process required to get new features or bugfixes implemented in CABLE trunk. Code that does not follow this proceedure will not be considered for inclusion in the CABLE trunk.

Development workflow

Prerequisites:

1. Read this document completely.
2. Get an accound on NCI, and ask to be added to the CABLE group.
3. Read the CABLE development guidelines on the Trac wiki.
4. Sign up to the CABLE email list (https://lists.csiro.au/mailman/listinfo/cable-users) to be alerted to CABLE developments
   • Check that the problem isn't already being addressed, by asking on the CABLE email list.
5. If you aren't already familiar with the CABLE codebase, have a read of the BeginnersGuide to CABLE development.

Submitting changes:

1. Copy the latest trunk version to a branch
   • If you will be the only contributor, create the branch at https://trac.nci.org.au/svn/cable/ branches/Users/[user]/[branch].
   • If you are working with others, create a shared branch at https://trac.nci.org.au/svn/cable/ branches/Share/SharedDevelopments/[branch].
2. Check out your branch.
3. Make code changes and commit them to your branch. Read the "Guidelines for committing" below.
4. Log in to the CABLE Jenkins project with your NCI login at https://climate-cms.nci.org.au/jenkins/job/CABLE.
5. Run the "branch_testing" job by clicking the clock with the green arrow ("build with parameters"), and entering your branch location, relative to the SVN root (e.g. Users//). This will run a series of tests, described below.
   • If testing fails unintentionally, read the logs to find out why, then go back to step 3, and repeat. For more details on the failure, read "Reading Jenkins Logs" below.
6. Log in to Trac, and create a new ticket describing your changes. Read the "Guidelines for Trac tickets" below.
7. Submit your ticket to the CABLE help email address ([email protected]).
8. The CABLE committee will review the changes, and may ask for additional manual testing and/or for further changes (in which case, go back to step 3).
9. If the change is accepted, a CABLE maintainer will merge your branch into the CABLE trunk. Your changes will be available in the next CABLE release (tagged version).

Guidelines for committing

• All new features must be switchable, with the switch off by default.
• Make sure all code changes follow the CableCodingConvention.
• Make sure all code is adequately documented, and that science code is appropriately referenced.
• All commits should contain adequate description of the changes being made, and list any contributors not already included in the commit info.

Recommended:

• Stick to the CABLE directory structure.
• Commit early, commit often, especially if using a shared branch.
• Keep commits as self-contained as possible. Do not submit two distinct bugfixes in one commit. Where it makes sense to, break large developments down into logical chunks. This makes it easier to discover and fix accidentally introduced bugs, and to avoid merge conflictss between developers working on the same code.
• Use SVN ignore lists to avoid committing unwanted files.

Reading Jenkins Logs

When the "branch_testing" job is run, it runs a series of other smaller jobs. In order to figure out the cause of a failure, you need to read the logs of the smaller jobs:

• On the "branch_testing" page, click the failed stage of your build, then click "logs"
• Usually the the failure will be the last build, which is the last listed link. Click that. That will take you to the build page of the sub-job.
• Click the "Console output" link on the left. This will show you the output of the job scripts. Usually the failure will be caused by some error that is listed at the end of the log.
• If you want to check the error and file status in more depth, you can log in to Raijin over ssh, and cd to the directory listed at the top of the "Console output" page, and read or run the files in the working directory. The data in this directory is only stored until the tests are next run.

Guidelines for Trac issues

Include:

• A description of the purpose of the code development and the resulting model behaviour.
• Link to the branch containing the changes.
• Link to the successful Jenkins results from the Trac ticket.
  • If the Jenkins results fail intentionally (e.g. due to science bug fixes that change the results of the testing simulations), then explain why your code changes cause those changes.
• Any appropriate technical documentation, user guide modifications or more detailed benchmarking results should be attached.

Testing

What will be tested?

All branches are tested with:

• Compile testing for offline, MPI-offline, and UM library; using both gfortran and ifort.
• Compile testing as above, with all warnings on.
• Run testing for Offline, MPI-offline.
• Checks for bitwise identical results from Offline and MPI-offline simulations.
  • (If bitwise tests fail) Basic science testing, showing benchmarking results, in comparison to Trunk.
• Compile and run CABLE in ACCESS, and check for bitwise identity with runs from the latest version of trunk.

What can't be tested

• It's not possible to show that the science of CABLE is correct using automated testing, though we may sometimes be able to show that it's incorrect.
• Whether code is adequately documented.