Releases and Versioning

Releases and Versioning

OpenAPC makes use of GitHub's release system to tag and version any changes in its aggregated data. This principle has been in place since the project's establishment in June 2014, when the first release was created. To keep track of the releases, we tag them following roughly the concept of semantic versioning (https://semver.org/). While this general approach did not change during OpenAPC's life time, the format and interpretation of the version numbers underwent some modifications, which are described below.

First phase

• From: Jun 18, 2014 (v1.0.0)

• Until: Dec 23, 2015 (v1.2.002)

• Format: aa.bb.cc

Version numbers should be interpreted as follows:

• aa: major release number, to be increased when there's an incompatible change to the data schema (did not happen during first phase).
• bb: minor release number, to be increased when there are "considerable improvements" to the data collection. Example: First inclusion of hybrid APCs.
• cc: patch number, to be increased with every new data ingestion.

Second phase

• From: Jan 27, 2016 (v2.0.0)

• Until: Aug 27, 2020 (v3.86.4)

• Format: aa.bb.cc

Version numbers should be interpreted as follows:

• aa: major release number, to be increased when there's an incompatible change to the data schema (did occur once with the integration of the issn_l field in September 2016, bringing the version from v2.11.0 to v3.0.0).
• bb: minor release number, to be increased when a new participant joins OpenAPC (whenever this happens, the patch number is set to 0 again). Note that this does not necessarily correspond to the number of new entities in the institution column. For instance, when an aggregator like Jisc or Couperin provides new data to OpenAPC, the ingestion might introduce several new institutions, but the minor release number is still only increased by one.
• cc: patch number, to be increased when an institution already taking part in OpenAPC provides new data. Reset to 0 with each new minor release.

Notes:

• The second phase system was introduced together with an incompatible change to the OpenAPC metadata schema, consequently starting with major version 2. Aside from the format changes, v2.0.0 is equivalent to its predecessor v1.2.002 in terms of data.
• Very small additions to a data submission usually do not trigger a new patch number (Example: An institution provides 100 new articles and then sends 2 more records they discovered some days later).
• Releases which are (mainly) error corrections to existing data also do not increase the patch number, instead they are marked with a "-fixed" suffix (Example).
• The second phase versioning system has one major drawback: It does only cover the main OpenAPC article data set (this is also true for the first phase, but at that time there was no other collection to worry about). When the offsetting data set (later to become the Transformative Agreements or TA collection) was established in June 2016, it's ingestions and changes were never tracked by the release system. The establishment of OpenAPC's third data collection (BPCs) in 2020 made it clear that the phase 2 system was no longer suitable.

Third phase

• From: Sep 3, 2020 (v4.0.0-0-0)

• Format: aa.bb.cc-dd-ee

Version numbers should be interpreted as follows:

• aa: major release number, to be increased when there's an incompatible change to any data schema (strictly speaking there was no such change when transitioning from v3, but the coverage of additional data sets still made a new major release appropiate).
• bb: minor release number, to be increased when a new participant joins OpenAPC (like in phase 2)
• cc-dd-ee: patch number is now a triple, with each component identifying one data collection (cc = APC data set, dd = transformative agreements data set, ee = BPC data set). Any change to one of the collections is to be denoted by incrementing the according component.

Notes:

• In terms of data, v4.0.0-0-0 is equivalent to its predecessor v3.86.4
• When an (already participating) institution provides data to more than one data set, the components should be increased together. Example: v4.8.3-2-0 would become v4.8.4-2-1 when a participant delivers both new APC and BPC data.
• When a new institution joins, the patch triple is reset, but not to 0-0-0. Instead, the initial data provided by the institution should already be taken into account. Example: An institution joining with new APC data would make v4.8.4-2-1 transition into v4.9.1-0-0.
• Rules from phase 2 regarding small additions and error corrections also apply to phase 3.