Record Layer Versions

Variants

The Record Layer is released in several variants, depending on which version of the Protobuf API is used and whether or not Protobuf is renamed (“shaded”).

  Protobuf 2 Protobuf 3
Unshaded fdb-record-layer-core fdb-record-layer-core-pb3
Shaded fdb-record-layer-core-shaded fdb-record-layer-core-pb3-shaded

In the shaded versions, com.google classes will be renamed to com.apple.foundationdb.record.shaded.com.google.

Code generated by one version of protoc is generally not compatible with the Protobuf runtime classes from another version.

Maven Dependency

  <groupId>org.foundationdb</groupId>
  <artifactId>fdb-record-layer-core</artifactId>
  <version>2.8.+</version>

Gradle Dependency

"org.foundationdb:fdb-record-layer-core:2.8.+"

Semantic Versioning

Record Layer versions are major.minor.build.patch.

New versions are typically cut off of the master branch of the Record Layer repository. In that case, the major and minor versions are specified by the version property within gradle.properties and the patch version will be 0. (The build version is monotonically increasing.) However, in certain circumstances, bug fixes or even some backwards-compatible features might be cherry-picked to older releases. In that case, the patch will be non-zero and the major, minor, and build versions will match the version of the older release.

The corollary to this is that it is not always true that a “newer” version of the Record Layer contains all changes in an “older” version (where “newer” and “older” are determined only by looking at the version number). For example, suppose a bug is discovered on master and the fix is released as part of version 2.3.31.0 and also back-ported and included in version 2.2.29.7. Then the fix won’t be in version 2.3.30.0 even though 2.3.30.0 is “newer” than 2.2.29.7. In general, however, the following should be the case:

  • Version a.b.c1.0 contains all changes in version a.b.c2.0 if c1 > c2.
  • Version a.b.c.d1 contains all changes in version a.b.c.d2 if d1 > d2.

Users are encouraged to check the release notes to see when changes introduced in a patch branch are made available in the master release train.

API Stability Annotations

Classes and methods annotations using @API determine when they can be changed in a backwards-incompatible way or removed. See the Javadoc for more details.

  • STABLE will not change until the major version is incremented. At that time, they may also change status to something less stable.

  • MAINTAINED will not change until the minor version is incremented. At that time, only the status changes to UNSTABLE or DEPRECATED. This indicates that in the next minor version they will change / be removed.

  • UNSTABLE can change in a minor release without other advance notice.

  • DEPRECATED can be removed in a minor release without other advance notice.

  • EXPERIMENTAL can change / be removed in any build without notice.

Creating a Patch Branch

  • Patch branches should be named fdb-record-layer-a.b.c after the build from which they are created.

  • The new patch branch should be made using the tag created for the starting build.

      git checkout -b fdb-record-layer-a.b.c a.b.c.0
    
  • In gradle.properties, change

      version=a.b
    

    to

      version=a.b.c
    

    using the starting version.

  • In docs/ReleaseNotes.md, move the template for release notes for the next release to be just above the release note for the starting version a.b.c.

  • Commit and push the new branch upstream.

  • Create patch fix pull requests against this new branch.

  • There may be conflicts in the gradle.properties and docs/ReleaseNotes.md files when the patch branch is merged into master. Be sure whenever merging that branch in that (1) the version on master is not accidentally changed and (2) the release notes file contains all release notes from both branches after the merge.