GEOS-Chem version numbering system

From Geos-chem
Revision as of 20:10, 14 June 2018 by Bmy (Talk | contribs) (GEOS-Chem alphanumeric version number system (now retired))

Jump to: navigation, search

Page is under construction.jpg

GEOS-Chem alphanumeric version number system (now retired)

GEOS-Chem versions v9-02 through v11-02 have used an alphanumeric system to denote major versions as opposed to intermediate checkpoint versions where several new features were evaluated with 1-month and/or 1-year benchmarks. The table below shows examples of past version numbers.

NOTE: All intermediate checkpoint versions were validated with a 1-month benchmark. Some intermediate checkpoint versions were validated with 1-month and 1-year benchmarks.

Action Resulting version #
GEOS-Chem 10 public release v10-01-public
First intermediate checkpoint of v11-01
  • New features and/or fixes added and validated with 1-month benchmark
v11-01a
Second intermediate checkpoint of v11-01
  • New features and/or fixes added and validated with 1-month benchmark
v11-01b
...etc Intermediate checkpoint versions... v11-02c thru v11-01k
v11-01 "provisional" release
  • The version prior to the final v11-01 release
  • Users were encouraged to download, test, report bugs
v11-01-provisional
GEOS-Chem v11-01 "public" release v11-01-public
First intermediate checkpoint version of v11-02
  • New features and/or fixes added and validated with 1-month benchmark
v11-02a
Second intermediate checkpoint version of v11-02
  • New features and/or fixes added and validated with 1-month benchmark ||v11-02b
...etc intermediate checkpoint versions ... v11-02c thru v11-01f
v11-02 "release candidate"
  • Formerly called "provisional"
  • Users were encouraged to download, test, report bugs
v11-02-release-candidate
GEOS-Chem v11-02 final release
  • Formerly called "public", but this practice has been discontinued
v11-02-final

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 the next GEOS-Chem "release candidate";
  • aka The version immediately preceding the next major release
  • Users are encouraged to download and test and report bugs/issues
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 GEOS-Chem wiki.

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)