Minor Version Update Protocols

Major/Minor Version Update Protocols

Minor version updates are when the second number in the tag changes (i.e. ctsm6.0.176 to ctsm6.1.0). Major version updates are when the first number changes (i.e. ctsm6.5.176 to ctsm7.0.0). Major version updates follow this as well and just add additional requirements.

Planning for next minor version

After completion of a minor version update, we start planning for the next one. Things to decide in the planning phase:

• Version name it will be called
• Requirements -- List of features desired to bring in (include priority level)
• Additional test requirements (if any besides below)
• Simulation requirements (simulations to go along with the updated version) (if any)
• Finishing criteria -- is the deadline when the list of requirements done? Or at a fixed date? Or some compromise between the two?
• Estimated deadline

A workplan of assignments for people to accomplish the list of requirements should also be done, with issues created and tasks figured out. A milestone is created in github.

Required testing

• Run the following tests: namelist, python, aux_clm, ctsm_sci, fates, mosart, rtm

• ctsm_sci baselines have a ctsm_sci- prefix to the tag name

• FATES baselines have the normal fates- prefix with the FATES version and then the CTSM version

• mosart baselines have the mosart version as a prefix

• rtm baselines have the rtm version as a prefix

• Simulations should be performed and verified at least working up to the final version (normally spinup and transient for standard resolution)

• Compare baseline test namelists between previous ctsm_sci testrun and new tag (make sure differences are expected)

cd bld/unit_tests
./cmp_baseline_lnd_in_files <previous_tag> <new_tag>

• Compare namelists between the previous tag and what will become the new minor version update

cd $SCRATCH
git clone --origin escomp -b <previous_tag> https://github.com/ESCOMP/CTSM.git <previous_tag>
cd bld/unit_testers
./build-namelist_test.pl --generate
cd <location_of_clone_for_new_tag>
cd bld/unit_testers
./build-namelist_test.pl --compare $SCRATCH/bld/unit_testers
./compare_namelists -b $SCRATCH/bld/unit_testers -pa clm4_5 -pb clm4_5
./compare_namelists -b $SCRATCH/bld/unit_testers -pa clm5_0 -pb clm5_0
./compare_namelists -b $SCRATCH/bld/unit_testers -pa clm6_0 -pb clm6_0

• Similarly compare namelists between the previous tag that had ctsm_sci testing on it and what will become the new minor version update
• Similarly compare namelists between the previous minor version tag and what will become the new minor version update

Make sure that the changes appear as expected.

When a new physics version option is added

Compare the ctsm_sci tests by making sure all the new tests are run in the older version (with the previous physics version) Create softlinks to the new version in the previous ctsm_sci test baseline that have the new version in it Compare the new namelists to the older one to make sure the changes are as expected

cd bld/unit_testers
./build-namelist_test.pl
./compare_namelists --physicsA <old_physics_version> --physicsB <new_physics_version>

Required review

• Review the final version before it comes in as a tag.
• Review the README files to make sure they are still accurate
• ChangeLog for the final minor version update tag include a summary of changes from the last minor version
• Have several people review what will become the new minor version

Additional tasks

• Run standard simulations with the final tag (f09 1850-spinup, transient-historical)
• Upgrade to a release (on github under tag) if simulations are good
• Upgrade updated version to a release once simulations are good in a follow on tag

Major Version Update Additions

• Simulations are required to go along with a major version update
• User's Guide and Technical note need to be extensively updated