Versioning Conventions

Versioning

Version tagging is based on a major.minor.patch numbering scheme.

• The major number is incremented after extensive rewrites or substantial overhauls that may significantly affect workflow integration or user experience. Major updates undergo extensive testing, but subsequent patch updates may still be needed.

• The minor number is incremented whenever modifications to the source code are significant enough to require updates to parameter files or other input files.

• The patch number is used to denote bug fixes or other minor revisions. Updates to parameter files or other input files are not required.

In the past, tagged releases have been fairly infrequent because the associated testing is very time consuming. Now that a buildbot system and testing framework are being put in place, the frequency of such releases is expected to increase.

SPECFEM versioning example

How do we set the version number for a SPECFEM code? The version tagging could look as following (after discussing also with Robert Knight & Dennis McRitchie for shakemovies at PICSciE Princeton):

• major number increase, e.g. 5.0.1 -> 6.0.0

  • if a major feature is added
  • if a major restructuring of the code was done

• minor number increase, e.g. 5.0.1 -> 5.1.0

  • if a minor feature is added
  • if something in the file format changed:
    e.g., a new parameter in constants.h such that the new code would not compile anymore with the old constants.h

• minuscule number increase, e.g. 5.0.1 -> 5.0.2

  • for bug fixes
  • if only a very minor feature is added without changing any input parameter files

Checklist for updating to a new version

The following is a checklist to go through when updating the release version:

• update version numbers in files:

  • VERSION file
  • configure.ac, update configure script by: > autoreconf -i
  • doc/USER_MANUAL/manual_SPECFEM3D_Cartesian.tex
  • (globe code) setup/adios_xml_files/par_header.xml
  • (globe code) src/specfem3D/write_output_SAC.f90

• add version information to header in files:

  • src/meshfem3D/meshfem3D.f90
  • src/specfem3D/specfem3D.F90
  • doc/USER_MANUAL/copyright_and_version.tex

• update development plan:

  • wiki/Development-plan.md

• announcement:

  • what is new?
  • what has changed?
  • what bug fixes are done?