Record Layer Versions

Variants

The Record Layer is released in two variants, depending on not Protobuf is renamed (“shaded”).

Unshaded: fdb-record-layer-core
Shaded: fdb-record-layer-core-shaded

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

Note that code generated by one version of protoc is generally not compatible with the Protobuf runtime classes from another version. For that reason, it is suggested that the adopter keep their protoc version aligned with the Protobuf runtime used by the Record Layer library.

Maven Dependency

For the most up-to-date builds, the following maven repo should be added to the repositories section:

<repositories>
  <repository>
    <id>fdb-record-layer</id>
    <name>FDB Record Layer</name>
    <url>https://ossartifacts.jfrog.io/artifactory/fdb-record-layer</url>
  </repository>
</repositories>

Then the following dependency can be added:

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

Older builds are also available in the maven central repository, and newer builds will be published there upon the resolution of Issue #1288.

Gradle Dependency

For the most up-to-date builds, the following maven repo should be added to the repositories section:

repositories {
  mavenCentral()
  maven {
    url "https://ossartifacts.jfrog.io/artifactory/fdb-record-layer/"
  }
}

Then the following dependency can be added:

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

Older builds are also available in the mavenCentral() repository, and newer builds will be published there upon the resolution of Issue #1288.

Semantic Versioning

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

New versions are typically cut off of the main 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 main 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 main 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 main. Be sure whenever merging that branch in that (1) the version on main is not accidentally changed and (2) the release notes file contains all release notes from both branches after the merge.