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, all the way back to the ctsm_sci of the last minor version. Make sure differences are expected.

cd bld/unit_testers
./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
# Before executing build-namelist_test.pl here and a few lines down, make sure that the respective /unit_testers directories do not contain old lnd_in..., temp_..., and drv_flds_in... files that will likely confuse the comparisons that you are about to initiate.
./build-namelist_test.pl --generate
cd <location_of_clone_for_new_tag>
cd bld/unit_testers
./build-namelist_test.pl --compare $SCRATCH/<previous_tag>/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

It helps to send these comparisons to files and use grep or other tools to filter out expected changes to make unexpected changes stand out.

• 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.

• Compare new versus old parameter files using "cprnc -m" to see if fields were changed 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>

When surface datasets are being updated

When surface datasets are being updated, there is additional process

• Create alpha branch for the updates (try to put ONLY the changes that are needed here, put everything that can go to main-dev there)
• Bring in the needed updates to mksurfdata_esmf and the input (also known as raw) datasets
• Create a few new datasets at standard model resolutions (currently f09 and ne30np4.pg3)
• Do general validation on them comparing to previous versions
• Run simulations with the new datasets -- validate that changes to climate are as expected (this is part of the simulations that go with the minor version tag)
• Work with CAM and CESM to determine what grids need to be created (use a similar spreadsheet to this one: https://docs.google.com/spreadsheets/d/1Osq56e423CF107zhoNQ0VS7-iH_JXLF9AtCvBdXyfJ4/edit?gid=0#gid=0)
• Make sure all datasets can be created using "make all" in the mksurfdata_esmf tool
• Validate that surface datasets are bit-for-bit with different number of processors (at least one standard resolution)
• Create a tag on the alpha branch to create the datasets with
• Create all the datasets with the alpha tag
• Add the new datasets to the XML (bld/namelist_files/namelist_defaults_ctsm.xml) on the branch
• Bring in updated initial condition datasets and update the XML
• Resolve issues with testing
• ./rimport the new datasets, followed by relink.py in /glade/campaign/cesm/cesmdata/cseg/inputdata
• Continue with other steps

As one part of validating the new surface datasets, edit and then run the following script

tools/mksurfdata_esmf/validate_fsurdat_files.sh

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