Release Versioning

From Crypto++ Wiki
Jump to navigation Jump to search

Release Versioning is the process of assigning version numbers to software releases. Versioning helps manage the project in four ways. First, it allows us to refer to a particular state of the source code using friendly names, like Crypto++ 5.6.2 rather than a check-in number like R541. Second, it helps convey significance to a unique state of the software in time. Third, it helps locate a previous software state in source control, if needed. Fourth, it helps convey information about ABI and API compatibility.

This pages discusses how the project names a version of Crypto++, what to expect when a version number changes, and how to locate a particular state of the source code in Subversion or Git. The page also provides a brief history of releases. A related topic is Release Testing, and what it takes to release a version of Crypto++.

There is no definitive guide on versioning requirements, but it is important to follow best practices when a change occurs. The version number assigned to a release often conveys information on both ABI and API compatibility. Best practices often attempt to capture client compatibility requirements, especially in the context of shared objects and dynamic linking.

Header files with definitions and inlined functions makes consistent versioning a challenge because the library attempts to respect requirements on a number of different platforms. Each platform, like Debian and Apple, has its own expectation of what changes when a number is incremented or bumped. Some distributions, like Debian, will also monitor source control for a tagged release event and then automatically kick-off an update. Since its an automatic process, care must be taken to avoid problems for down stream.

Currently there is no process to evaluate the effects of changing source code on the ABI or API. The project does not use an ABI tracker in order to automate binary compatibility analysis. The project would like to add it in the future.

Scheme

Crypto++ historically utilizes a scheme consisting of a prefix and monotonically increasing version for naming releases. The prefix is CRYPTOPP, and the version consists of Major, Minor, and an optional Compatibility (or Patch). Each part of the name is separated with an underscore or _. Sometimes the third number is omitted when it is 0.

The library does not use the 4th tuple, sometimes called Revision, and it does not use letters like a or b. In addition, the library does not use an odd/even scheme. Finally, the library does not name release candidates.

Examples of the name are CRYPTOPP_2_3, CRYPTOPP_5_6_2 and CRYPTOPP_8_5.

Releases

Crypto++ releases are shown in the table below. The first column is the version, the second column is the tag name, the third column is the filesystem date. The filesystem date is the time on the server, and not the release date reported by subversion.

The fourth column is the symbolic define from config.h. The symbolic define is CRYPTOPP_VERSION. The fifth column is the filename made available for download. The sixth and seventh columns provide revision and check-in numbers, if available.

Crypto++ Versions and Names
Version Tag Name Date config.h Filename SVN Git
8.6 CRYPTOPP_8_6_0 2021-09-24 860 cryptopp860.zip N/A 69bf6b53052b
8.5 CRYPTOPP_8_5_0 2021-03-07 850 cryptopp850.zip N/A f2102243e6fd
8.4 CRYPTOPP_8_4_0 2021-01-02 840 cryptopp840.zip N/A 434e3189db61
8.3 CRYPTOPP_8_3_0 2020-12-20 830 cryptopp830.zip N/A d71bc515eafc
8.2 CRYPTOPP_8_2_0 2019-02-22 820 cryptopp820.zip N/A 9dcc26c58213
8.1 CRYPTOPP_8_1_0 2019-02-22 810 cryptopp810.zip N/A 1c34979592f7
8.0 CRYPTOPP_8_0_0 2018-12-28 800 cryptopp800.zip N/A 5e5fb6c855e0
7.0 CRYPTOPP_7_0_0 2018-04-08 710 cryptopp710.zip N/A c8d8caf70074655a
6.1.0 CRYPTOPP_6_1_0 2018-02-22 610 cryptopp610.zip N/A 5be140bcea453a00
6.0 CRYPTOPP_6_0_0 2018-01-22 600 cryptopp600.zip N/A b6c6684451f925ab
5.6.5 CRYPTOPP_5_6_5 2016-10-11 565 cryptopp565.zip R608 c621ce053298fafc
5.6.4 CRYPTOPP_5_6_4 2016-09-11 564 cryptopp564.zip R606 4132d85888ac6c30
5.6.3 CRYPTOPP_5_6_3 2015-11-20 563 cryptopp563.zip R604 298988a5b9687f64
5.6.2 CRYPTOPP_5_6_2 2013-02-20 562 cryptopp562.zip R541 789f81f048c9bc47
5.6.1 CRYPTOPP_5_6_1 2010-08-10 561 cryptopp561.zip R521 1088b555df20a9a0
5.6 CRYPTOPP_5_6_0 2009-03-27 560 cryptopp560.zip R460 88e0d157d71d7c39
5.5 CRYPTOPP_5_5 2007-05-05 372 cryptopp55.zip R372 0f71ab33118145a6
5.4 CRYPTOPP_5_4 2006-12-22 273 cryptopp54.zip R273 b696b90551981ac7
5.3.0 CRYPTOPP_5_3_0 2006-09-06 N/A cryptopp53.zip R240 89c4ed412bbf7be9
5.2.3 CRYPTOPP_5_2_3 2005-09-03 N/A cryptopp523.zip R206 ca1ab75604036ecd
5.2.1 CRYPTOPP_5_2_1 2004-07-22 N/A cryptopp521.zip R189 23c0e50c3e59157d
5.2 CRYPTOPP_5_2 2004-06-29 N/A cryptopp52.zip R179 40cb58f1f41ae823
5.1 CRYPTOPP_5_1 2003-03-22 N/A cryptopp51.zip R49 b2f710a955224978
5.0 CRYPTOPP_5_0 2002-10-04 N/A cryptopp50.zip R5 bf7ae380112674ec
Crypto++ 4 and earlier were in CVS. There is no historical source control record, other than filesystem names and dates.
4.2 2001-11-06 crypto42.zip
4.1 2001-01-14 crypto41.zip
4.0 2000-11-03 crypto40.zip
3.2 2000-03-20 crypto32.zip
3.1 1999-04-28 crypto31.zip
3.0 1999-01-01 crypto30.zip
2.3 1998-01-17 crypto23.zip
1.0 1995-06-01

Crypto++ supplied the macro CRYPTOPP_VERSION at X.Y.Z.
Crypto++ migrated from Sourceforge to Git in August, 2015.

Increment

After releasing the library the project's version should be bumped, even for SVN and GitHub. For example, if Crypto++ 5.6.4 was released, then the compatibility number should be changed from 4 to 5 in in 5.6.5. And if Crypto++ 5.7.0 was released, then the version should be changed to 5.7.1.

This change helps with user questions that start with "I'm using Crypto++ 5.6.3 and I'm having problems with ...". When the project encounters the question, its unclear if its the 5.6.3 release ZIP, or Master without the next version bump. The change also helps determine the actual compatibility level during development. That is, if Master advertises version information X.Y.Z, then it better be compatible with X.Y.

Its also OK to release under a more appropriate version number. For example, the following is perfectly valid: release 5.6.3, bump to 5.6.4 during development, and then release 5.7.0. In this case version information is monotonically increasing, and there is no confusion or disambiguation needed.

The locations of version numbers are:

  • config.h and CRYPTOPP_VERSION
  • cryptlib.h and Doxygen comment
  • cryptopp.rc and VERSION_INFO block
  • GNUmakefile and libcryptopp.pc recipe
  • Doxyfile and PROJECT_NUMBER
  • Readme.txt and version number
  • change-version.sh in TestScripts

Also see the discussion Post-release version number increment on the user mailing list.