# 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, add the following maven dependency:

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

For builds older than 4.1 but newer than 2.8, an additional repository must be added to the build configuration, as older versions were not published to Maven Central:

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

See: [Issue #1288](https://github.com/FoundationDB/fdb-record-layer/issues/1288).

### Gradle Dependency

For the most up-to-date builds, the following dependency can be added to gradle:

```
repositories {
  mavenCentral()
}

dependencies {
  implementation "org.foundationdb:fdb-record-layer-core:4.1.+"
}
```

For builds older than 4.1 but newer than 2.8, an additional repository must be added to the build configuration, as older versions were not published to Maven Central:

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

See: [Issue #1288](https://github.com/FoundationDB/fdb-record-layer/issues/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](https://javadoc.io/page/org.foundationdb/fdb-extensions/latest/com/apple/foundationdb/API.html) 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.

* `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/sphinx/source/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/sphinx/source/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.