GEOS-Chem version numbering system

From Geos-chem
Revision as of 19:10, 14 June 2018 by Bmy (Talk | contribs) (Example)

Jump to: navigation, search

Page is under construction.jpg

GEOS-Chem alphanumeric version number system (now retired)

GEOS-Chem numeric version number system

In order to transition between the alphanumeric and numeric versioning systems, the upcoming GEOS-Chem release v11-02-final will also carry the version number 12.0.0.

In order to conform more closely to industry-standard software versioning protocol, we are introducing a new system for GEOS-Chem version labelling. This system is loosely based on Semantic Versioning.

Overview

We will retire the alphanumeric versioning system (e.g. v11-02a, v11-02b, v11-02c, ...) and instead using 3 numbers of form X.Y.Z, as described in the table below.

Digit Description When is this digit incremented?
X Major version number.
  • Analogous to previously-termed "public" releases
X is incremented when we introduce an update that immediately breaks backward compatibility with the previous series of GEOS-Chem versions.

Examples:

  • Replacing old emissions code (v9-02) with HEMCO (v10-01)
  • Replacing the SMVGEAR chemistry solver (v10-01) to FlexChem/KPP (v11-01)
Y Benchmark number (aka feature number)
  • Denotes a collection of new features
  • Analogous to previous lettered versions
Y changes when a new set of features is validated with a 1-month benchmark.
  • Some (but not all) Y versions will have an associated 1-year benchmark.

NOTE: Any change to a GEOS-Chem run directory (that is, modifying input.geos, HEMCO_Config.rc, HISTORY.rc, etc.) necessitates that Y be incremented.

Z Bug fix number (aka patch number) Z changes when the following types of updates are added to the code:
  • Fixes for specialty simulations that do not affect the full-chemistry benchmark simulations
  • Fixes for bugs or technical issues that do not break backwards compatibility with the last benchmarked version (e.g. X.Y.0)

NOTE: All patched X.Y.Z versions of GEOS-Chem will remain compatible with the run directories from the last benchmarked version (X.Y.0).

--Bob Yantosca (talk) 18:59, 14 June 2018 (UTC)

Example

The numeric versioning system is illustrated in the table below.

NOTE: The 12.Y.Z version numbers listed in the table below are just for the purposes of illustration. They do not correspond to actual versions that have been released.

Action Resulting version #
The GEOS-Chem v11-02 major release is issued v11-02-final, aka 12.0.0
A bug is fixed, but does not break backwards compatibility 12.0.1
Several new features are added and tested with a 1-month benchmark 12.1.0
Fixed a bug identified during the benchmark 12.1.1
Fixed a second bug identified during the benchmark 12.1.2
More new features are added and tested with a 1-month benchmark 12.2.0
Fixed a bug identified during the benchmark 12.2.1
...etc. 12.Y.Z
Issued "release candidate";
  • The version immediately preceding the next major release, where users can download and test and report any bugs
12.N.0 (N is TBD)
The next major version of GEOS-Chem is released 13.0.0'

--Bob Yantosca (talk) 18:59, 14 June 2018 (UTC)

Documentation

The GEOS-Chem manual will be rewritten for each "major" release X.0.0. But the GEOS-Chem wiki will be updated for each benchmark and patch version X.Y.Z. Since GEOS-Chem v11-01, much of the GEOS-Chem manual now points to information on the wiki. Therefore

GEOS-Chem users will no longer need to wait for a major release (X.0.0), but instead can download the most recent version (X.Y.Z) when starting a new research project.

--Bob Yantosca (talk) 18:59, 14 June 2018 (UTC)