# Setup

## 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.