Difference between revisions of "GEOS-Chem version numbering system"
(→GEOS-Chem alphanumeric version number system (now retired)) |
(→Documentation) |
||
(36 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | + | '''''[[GEOS-Chem versions|GEOS-Chem versions page]]''''' | |
− | GEOS-Chem | + | This page describes the version numbering systems used by GEOS-Chem. We will transition from an [[#Alphanumeric versioning system (now retired)|alphanumeric system]] to a [[#Numeric versioning system|purely numeric versioning system]] with the [[GEOS-Chem v11-02|v11-02-final]] release. |
+ | |||
+ | == Alphanumeric versioning system (now retired) == | ||
− | + | GEOS-Chem versions [[GEOS-Chem v9-02|v9-02]] through [[GEOS-Chem v11-02|v11-02]] have used an alphanumeric version number system to denote major versions as opposed to intermediate checkpoint versions. The table below lists several previous GEOS-Chem versions that used the this system. | |
{| border=1 cellspacing=0 cellpadding=5 | {| border=1 cellspacing=0 cellpadding=5 | ||
Line 61: | Line 63: | ||
|} | |} | ||
− | |||
− | + | ''NOTES:'' | |
+ | #''All intermediate checkpoint versions were validated with a 1-month benchmark. Some intermediate checkpoint versions were validated with both 1-month and 1-year benchmarks. For clarity, we have not denoted the checkpoint releases for which 1-year benchmarks were also done.'' | ||
+ | #''We have listed the version numbers in the table from oldest at the top to newest at the bottom. This more clearly shows the progression of version numbers. Note that this is the opposite of how versions are displayed in the Git history.'' | ||
− | We have since discontinued the term "public | + | === Limitations of the alphanumeric system === |
+ | |||
+ | Prior to [[GEOS-Chem v11-02]], intermediate checkpoint versions were not made available to GEOS-Chem users. Because of this, the last version in a series was always denoted as the "public" release (e.g '''v9-02-public''', '''v10-01-public''', etc.). This made sense at the time, because the "public" version was the version that GEOS-Chem users would would be able to download. The [http://manual.geos-chem.org GEOS-Chem manual] was only updated for each "public" version. | ||
+ | |||
+ | We have since discontinued the term "public version", as GEOS-Chem users are now invited to download any intermediate checkpoint release when starting a research project. The last version in the v11-02 series will now be named '''v11-02-final'''. | ||
The practice of issuing a "provisional" or "release candidate" version immediately prior to the "final" release in a series began with [[GEOS-Chem v9-02]]. This was intended as a way of allowing users to take the "release candidate" version for a test-drive and to report any bugs or issues to the [[GEOS-Chem Support Team]]. The GCST would then be able to fix the issues for the "final" release. | The practice of issuing a "provisional" or "release candidate" version immediately prior to the "final" release in a series began with [[GEOS-Chem v9-02]]. This was intended as a way of allowing users to take the "release candidate" version for a test-drive and to report any bugs or issues to the [[GEOS-Chem Support Team]]. The GCST would then be able to fix the issues for the "final" release. | ||
− | While this versioning system worked well, it is not in line with accepted software industry best practice. Also the change in terminology from "public" to "final" and "provisional" to "release candidate", while well-intentioned, can lead to confusion. Furthermore, an intermediate checkpoint version number such as v11-02c does not distinguish between the addition of new features as opposed to bug fixes. For these reasons, we are migrating to a purely numeric version numbering system, as discussed in the following section. | + | While this versioning system worked well, it is not in line with accepted software industry best practice. Also the change in terminology from "public" to "final" and from "provisional" to "release candidate", while well-intentioned, can lead to confusion. Furthermore, an intermediate checkpoint version number such as v11-02c does not distinguish between the addition of new features as opposed to bug fixes. For these reasons, we are migrating to a purely numeric version numbering system, as discussed in the following section. |
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:47, 14 June 2018 (UTC) | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:47, 14 June 2018 (UTC) | ||
− | == | + | == Numeric versioning system == |
− | <span style="color:red">'''''In order to transition between the alphanumeric and numeric versioning systems, the upcoming GEOS-Chem release ''v11-02-final'' | + | <span style="color:red">'''''In order to transition between the alphanumeric and numeric versioning systems, the upcoming GEOS-Chem release ''v11-02-final'' also carries the version number 12.0.0.'''''</span> |
− | In order to conform more closely to industry-standard software versioning protocol, we shall retire [[# | + | In order to conform more closely to industry-standard software versioning protocol, we shall retire the use of [[#Alphanumeric versioning system (now retired)|alphanumeric version numbers]] (e.g. '''v11-02a''') for GEOS-Chem. Instead we shall adopt purely numeric version descriptors of the form '''X.Y.Z''', as described in the table below. (This system is loosely based on the idea of [https://semver.org/ Semantic Versioning].) |
{| border=1 cellspacing=0 cellpadding=5 | {| border=1 cellspacing=0 cellpadding=5 | ||
|-bgcolor="#CCCCCC" | |-bgcolor="#CCCCCC" | ||
− | !width="40px"| | + | !width="40px"|Number |
!width="350px"|Description | !width="350px"|Description | ||
!width="650px"|When is this digit incremented? | !width="650px"|When is this digit incremented? | ||
Line 91: | Line 98: | ||
|'''X''' is incremented when we introduce an update that immediately breaks backward compatibility with the previous series of GEOS-Chem versions. | |'''X''' is incremented when we introduce an update that immediately breaks backward compatibility with the previous series of GEOS-Chem versions. | ||
− | Examples: | + | Examples of when the major number was changed in past versions of GEOS-Chem: |
*Replacing old emissions code ('''v9-02''') with [[HEMCO]] ('''v10-01''') | *Replacing old emissions code ('''v9-02''') with [[HEMCO]] ('''v10-01''') | ||
*Replacing the SMVGEAR chemistry solver ('''v10-01''') to [[FlexChem|FlexChem/KPP]] ('''v11-01''') | *Replacing the SMVGEAR chemistry solver ('''v10-01''') to [[FlexChem|FlexChem/KPP]] ('''v11-01''') | ||
Line 120: | Line 127: | ||
=== Example === | === Example === | ||
− | + | A sample progression of GEOS-Chem version numbers using the purely numeric versioning system is illustrated in the table below. | |
− | + | ||
− | + | ||
{| border=1 cellspacing=0 cellpadding=5 | {| border=1 cellspacing=0 cellpadding=5 | ||
Line 133: | Line 138: | ||
|-valign="top" bgcolor="#CCFFFF" | |-valign="top" bgcolor="#CCFFFF" | ||
− | | | + | |Bugs are fixed, but this does not break backwards compatibility || '''12.0.1'''<br>'''12.0.2'''<br>'''12.0.3''' |
|-valign="top" | |-valign="top" | ||
− | | | + | |A collection of new features is added |
− | + | *and validated with a 1-month benchmark | |
− | + | *and maybe with a 1-year benchmark (if necessary) | |
− | + | | '''12.1.0''' | |
|-valign="top" | |-valign="top" | ||
− | | | + | |A bug identified during the benchmark is fixed || '''12.1.1''' |
|-valign="top" bgcolor="#CCFFFF" | |-valign="top" bgcolor="#CCFFFF" | ||
− | | | + | |Another collection of new features is added |
+ | *and validated with a 1-month benchmark | ||
+ | *and maybe with a 1-year benchmark (if necessary) | ||
+ | |'''12.2.0''' | ||
|-valign="top bgcolor="#CCFFFF" | |-valign="top bgcolor="#CCFFFF" | ||
− | | | + | |A bug identified during the benchmark is fixed || '''12.2.1''' |
|-valign="top" | |-valign="top" | ||
Line 154: | Line 162: | ||
|-valign="top" bgcolor="#CCFFFF" | |-valign="top" bgcolor="#CCFFFF" | ||
− | | | + | |The next GEOS-Chem "release candidate" is issued |
*aka The version immediately preceding the next major release | *aka The version immediately preceding the next major release | ||
*Users are encouraged to download and test and report bugs/issues | *Users are encouraged to download and test and report bugs/issues | ||
Line 164: | Line 172: | ||
|} | |} | ||
− | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) | + | |
+ | ''NOTES:'' | ||
+ | #''We have listed the version numbers in the table from oldest at the top to newest at the bottom. This more clearly shows the progression of version numbers. Note that this is the opposite of how versions are displayed in the Git history.'' | ||
+ | |||
+ | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 14:40, 15 June 2018 (UTC) | ||
=== Documentation === | === Documentation === | ||
− | The [ | + | The [https://geos-chem.readthedocs.io GEOS-Chem manual] and [https://gchp.readthedocs.io GCHP manual] will be rewritten for each release X.Y.Z. 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. |
+ | |||
+ | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:50, 1 June 2023 (UTC) | ||
+ | |||
+ | === GEOS-Chem Classic and GCHP versions === | ||
− | GEOS-Chem | + | For the sake of clarity, GEOS-Chem Classic and GCHP will be assigned the same version number. Therefore it is possible that a given version contains updates for GEOS-Chem Classic or GCHP, but not both. |
− | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) | + | --[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:04, 5 August 2021 (UTC) |
Latest revision as of 21:08, 1 June 2023
This page describes the version numbering systems used by GEOS-Chem. We will transition from an alphanumeric system to a purely numeric versioning system with the v11-02-final release.
Contents
Alphanumeric versioning system (now retired)
GEOS-Chem versions v9-02 through v11-02 have used an alphanumeric version number system to denote major versions as opposed to intermediate checkpoint versions. The table below lists several previous GEOS-Chem versions that used the this system.
Action | Resulting version # |
---|---|
GEOS-Chem 10 public release | v10-01-public |
First intermediate checkpoint of v11-01
|
v11-01a |
Second intermediate checkpoint of v11-01
|
v11-01b |
...etc Intermediate checkpoint versions... | v11-02c thru v11-01k |
v11-01 "provisional" release
|
v11-01-provisional |
GEOS-Chem v11-01 "public" release | v11-01-public |
First intermediate checkpoint version of v11-02
|
v11-02a |
Second intermediate checkpoint version of v11-02
|
v11-02b |
...etc intermediate checkpoint versions ... | v11-02c thru v11-01f |
v11-02 "release candidate"
|
v11-02-release-candidate |
GEOS-Chem v11-02 final release
|
v11-02-final |
NOTES:
- All intermediate checkpoint versions were validated with a 1-month benchmark. Some intermediate checkpoint versions were validated with both 1-month and 1-year benchmarks. For clarity, we have not denoted the checkpoint releases for which 1-year benchmarks were also done.
- We have listed the version numbers in the table from oldest at the top to newest at the bottom. This more clearly shows the progression of version numbers. Note that this is the opposite of how versions are displayed in the Git history.
Limitations of the alphanumeric system
Prior to GEOS-Chem v11-02, intermediate checkpoint versions were not made available to GEOS-Chem users. Because of this, the last version in a series was always denoted as the "public" release (e.g v9-02-public, v10-01-public, etc.). This made sense at the time, because the "public" version was the version that GEOS-Chem users would would be able to download. The GEOS-Chem manual was only updated for each "public" version.
We have since discontinued the term "public version", as GEOS-Chem users are now invited to download any intermediate checkpoint release when starting a research project. The last version in the v11-02 series will now be named v11-02-final.
The practice of issuing a "provisional" or "release candidate" version immediately prior to the "final" release in a series began with GEOS-Chem v9-02. This was intended as a way of allowing users to take the "release candidate" version for a test-drive and to report any bugs or issues to the GEOS-Chem Support Team. The GCST would then be able to fix the issues for the "final" release.
While this versioning system worked well, it is not in line with accepted software industry best practice. Also the change in terminology from "public" to "final" and from "provisional" to "release candidate", while well-intentioned, can lead to confusion. Furthermore, an intermediate checkpoint version number such as v11-02c does not distinguish between the addition of new features as opposed to bug fixes. For these reasons, we are migrating to a purely numeric version numbering system, as discussed in the following section.
--Bob Yantosca (talk) 20:47, 14 June 2018 (UTC)
Numeric versioning system
In order to transition between the alphanumeric and numeric versioning systems, the upcoming GEOS-Chem release v11-02-final also carries the version number 12.0.0.
In order to conform more closely to industry-standard software versioning protocol, we shall retire the use of alphanumeric version numbers (e.g. v11-02a) for GEOS-Chem. Instead we shall adopt purely numeric version descriptors of the form X.Y.Z, as described in the table below. (This system is loosely based on the idea of Semantic Versioning.)
Number | Description | When is this digit incremented? |
---|---|---|
X | Major version number.
|
X is incremented when we introduce an update that immediately breaks backward compatibility with the previous series of GEOS-Chem versions.
Examples of when the major number was changed in past versions of GEOS-Chem:
|
Y | Benchmark number (aka feature number)
|
Y changes when a new set of features is validated with a 1-month 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:
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
A sample progression of GEOS-Chem version numbers using the purely numeric versioning system is illustrated in the table below.
Action | Resulting version # |
---|---|
The GEOS-Chem v11-02 major release is issued | v11-02-final, aka 12.0.0 |
Bugs are fixed, but this does not break backwards compatibility | 12.0.1 12.0.2 12.0.3 |
A collection of new features is added
|
12.1.0 |
A bug identified during the benchmark is fixed | 12.1.1 |
Another collection of new features is added
|
12.2.0 |
A bug identified during the benchmark is fixed | 12.2.1 |
...etc. | 12.Y.Z |
The next GEOS-Chem "release candidate" is issued
|
12.N.0 (N is TBD) |
The next major version of GEOS-Chem is released | 13.0.0 |
NOTES:
- We have listed the version numbers in the table from oldest at the top to newest at the bottom. This more clearly shows the progression of version numbers. Note that this is the opposite of how versions are displayed in the Git history.
--Bob Yantosca (talk) 14:40, 15 June 2018 (UTC)
Documentation
The GEOS-Chem manual and GCHP manual will be rewritten for each release X.Y.Z. 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) 20:50, 1 June 2023 (UTC)
GEOS-Chem Classic and GCHP versions
For the sake of clarity, GEOS-Chem Classic and GCHP will be assigned the same version number. Therefore it is possible that a given version contains updates for GEOS-Chem Classic or GCHP, but not both.
--Bob Yantosca (talk) 15:04, 5 August 2021 (UTC)