Difference between revisions of "GEOS-Chem version numbering system"

From Geos-chem
Jump to: navigation, search
(Overview)
(GEOS-Chem alphanumeric version number system (now retired))
Line 3: Line 3:
 
== GEOS-Chem alphanumeric version number system (now retired) ==
 
== GEOS-Chem alphanumeric version number system (now retired) ==
  
GEOS-Chem versions [[GEOS-Chem v9-02|v9-02]] through [[GEOS-Chem v11-02|v11-02]] have used an alphanumeric system to denote major versions as opposed to checkpoint versions where several new features were evaluated with 1-month and/or 1-year benchmarks.  This version  
+
GEOS-Chem versions [[GEOS-Chem v9-02|v9-02]] through [[GEOS-Chem v11-02|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.''
  
 +
{| border=1 cellspacing=0 cellpadding=5
 +
|-bgcolor="#CCCCCC"
 +
!width="500px"|Action
 +
!width="200px"|Resulting version #
  
Starting with the [[GEOS-Chem v11-02]] major release, we are now
+
|-valign="top" bgcolor="#CCAA00"
 +
|GEOS-Chem 10 public release ||'''v10-01-public'''
 +
 
 +
|-valign="top"
 +
|New features and/or fixes added and validated with 1-month benchmark ||'''v11-01a'''
 +
 
 +
|-valign="top"
 +
|New features and/or fixes added and validated with 1-month benchmark ||'''v11-01b'''
 +
 
 +
|-valign="top"
 +
|...etc... ||'''v11-02c''' thru '''v11-01k'''
 +
 
 +
|-valign="top" bgcolor="#CCFFFF"
 +
|v11-01 "provisional" release
 +
*The version prior to the final v11-01 release
 +
*Users were encouraged to download, test, report bugs
 +
|'''v11-01-provisional'''
 +
 
 +
|-valign="top" bgcolor="#CCAA00"
 +
|GEOS-Chem v11-01 "public" release ||'''v11-01-public'''
 +
 
 +
|-valign="top"
 +
|New features and/or fixes added and validated with 1-month benchmark ||'''v11-02a'''
 +
 
 +
|-valign="top"
 +
|New features and/or fixes added and validated with 1-month benchmark ||'''v11-02b'''
 +
 
 +
|-valign="top"
 +
|...etc... ||'''v11-02c''' thru '''v11-01f'''
 +
 
 +
|-valign="top" bgcolor="#CCFFFF"
 +
|Issued the v11-02 "release candidate"
 +
*Formerly called "provisional"
 +
*The version prior to the final v11-02 release
 +
*Users were encouraged to download, test, report bugs
 +
|'''v11-02-release-candidate'''
 +
 
 +
|-valign="top" bgcolor="#CCAA00"
 +
|Released the final v11-02 version
 +
*Formerly called "provisional"
 +
*The version prior to the final v11-02 release
 +
*Users were encouraged to download, test, report bugs
 +
|'''v11-02-final
 +
 
 +
|}
  
 
== GEOS-Chem numeric version number system ==
 
== GEOS-Chem numeric version number system ==

Revision as of 20:06, 14 June 2018

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
New features and/or fixes added and validated with 1-month benchmark v11-01a
New features and/or fixes added and validated with 1-month benchmark v11-01b
...etc... 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
New features and/or fixes added and validated with 1-month benchmark v11-02a
New features and/or fixes added and validated with 1-month benchmark v11-02b
...etc... v11-02c thru v11-01f
Issued the v11-02 "release candidate"
  • Formerly called "provisional"
  • The version prior to the final v11-02 release
  • Users were encouraged to download, test, report bugs
v11-02-release-candidate
Released the final v11-02 version
  • Formerly called "provisional"
  • The version prior to the final v11-02 release
  • Users were encouraged to download, test, report bugs
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)