Release Versioning
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.
Tagging
Releases are tagged in version control. Git offers two types of tags but only one actually works. When tagging be sure to use Annotated tags, and not lightweight tags. Also see GitHub Issue 1087.
To create an annotated tag use the following:
$ git tag -s -a CRYPTOPP_8_7_0 -m "Crypto++ 8.7 release" $ git push origin CRYPTOPP_8_7_0
Do not use GitHub to create a tag. GitHub uses the wrong type of tag.
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.
| Version | Tag Name | Date | config.h | Filename | SVN | Git |
|---|---|---|---|---|---|---|
| 8.9 | CRYPTOPP_8_9_0
|
2023-10-01 | 880 | cryptopp890.zip | N/A‡ | 843d74c7c97f |
| 8.8 | CRYPTOPP_8_8_0
|
2023-06-25 | 880 | cryptopp880.zip | N/A‡ | 4d0cad5401d1 |
| 8.7 | CRYPTOPP_8_7_0
|
2022-08-07 | 870 | cryptopp870.zip | N/A‡ | 511806c0eba8 |
| 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.handCRYPTOPP_VERSIONcryptlib.hand Doxygen commentcryptopp.rcandVERSION_INFOblockGNUmakefileandlibcryptopp.pcrecipeDoxyfileandPROJECT_NUMBERReadme.txtandversion numberchange-version.shinTestScripts
Two additional projects should also have its version incremented. The first is Autotools, and the second is CMake.
Also see the discussion Post-release version number increment on the user mailing list.