# Releasing TensorFlow Java

The
[TensorFlow Java API](https://github.com/tensorflow/java) is available on Maven Central and JCenter
through artifacts uploaded to
[OSS Sonatype](https://oss.sonatype.org/content/repositories/releases/org/tensorflow/). This
document describes the process of updating the release artifacts. It does _not_ describe how to use
the artifacts, for which the reader is referred to the
[TensorFlow for Java installation instructions](https://github.com/tensorflow/java/blob/master/README.md).

## Background

TensorFlow source (which is primarily in C++) is built using
[bazel](https://bazel.build) and not [maven](https://maven.apache.org/). TensorFlow Java
wraps over this native code and thus depends on platform (OS, architecture) specific native code.

Hence, the process for building and uploading release artifacts is not a single
`mvn deploy` command.

## Release process overview

The process of releasing TensorFlow Java is split in two major steps:
* Building and deploying the native artifacts
* Building and deploying all artifacts consolidated

The first step is executed on different build servers, each responsible to build the native
artifact for a specific architecture and platform. The second step is conducted locally in
a [Docker](https://www.docker.com) container for a hermetic release process.

It is important to note that any change pushed to a release branch (i.e. a branch prefixed
by `r`) will start a new release workflow. Therefore, these changes should always increment the
version number.

### Pre-requisites

-   `docker`
-   An account at [oss.sonatype.org](https://oss.sonatype.org/), that has
    permissions to update artifacts in the `org.tensorflow` group. If your
    account does not have permissions, then you'll need to ask someone who does
    to [file a ticket](https://issues.sonatype.org/) to add to the permissions
    ([sample ticket](https://issues.sonatype.org/browse/MVNCENTRAL-1637)).
-   A GPG signing key, required
    [to sign the release artifacts](http://central.sonatype.org/pages/apache-maven.html#gpg-signed-components).

### Preparing a release

#### Major or minor release

1.  Get a clean version of the source code by cloning the
    [TensorFlow Java GitHub repository](https://github.com/tensorflow/java)
    ```
    git clone https://github.com/tensorflow/java
    ```
2.  Create a new branch for the release named `r.`
    ```
    git checkout -b r1.0
    ```
3.  Update the version of the Maven artifacts to the full version of the release
    ```
    mvn versions:set -DnewVersion=1.0.0
    ```
4.  Update the TensorFlow Java version to reflect the new release at the following locations:
    - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L61
    - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L167
    - https://github.com/tensorflow/java/blob/master/README.md#using-maven-artifacts
    - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-version-support

5.  Commit the changes and push the new branch to the GitHub repository
    ```
    git add .
    git commit -m "Releasing 1.0.0"
    git push --set-upstream origin r1.0
    ```

#### Patch release

1.  Get a clean version of the source code by cloning the
    [TensorFlow Java GitHub repository](https://github.com/tensorflow/java)
    ```
    git clone https://github.com/tensorflow/java
    ```
2.  Switch to the release branch of the version to patch
    ```
    git checkout r1.0
    ```
3.  Patch the code with your changes. For example, changes could be merged from another branch you
    were working on or be applied directly to this branch when the required changes are minimal.

4.  Update the version of the Maven artifacts to the full version of the release
    ```
    mvn versions:set -DnewVersion=1.0.1
    ```
5.  Update the TensorFlow Java version to reflect the new release at the following locations:
    - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L61
    - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L167
    - https://github.com/tensorflow/java/blob/master/README.md#using-maven-artifacts
    - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-version-support

6.  Commit the changes and push the branch to the GitHub repository
    ```
    git add .
    git commit -m "Releasing 1.0.1"
    git push
    ```

### Building native artifacts

Any change pushed to a release branch will trigger a new release workflow. GitHub Actions builds the native artifacts 
for all supported architures/platforms and deploy them temporarily on OSSRH for staging.

There is no user action required for this step other than watching the progress of the GitHub
Actions workflow and making sure that all steps have been completed successfully.

#### Build native artifacts manually

Some platforms cannot be build successfully on GitHub Actions, due to some limits to their resources
(e.g. max 6 hours for a job). For this reasons, we need to build manually some of our artifacts on
private servers. 

To do so, follow the same steps as the [CI build](https://github.com/tensorflow/java/blob/master/.github/workflows/ci.yml)
for the same platform and make sure to checkout the release branch and to provide your Sonatype credentials
for temporary staging.

### Performing the release

1.  At the root of your TensorFlow Java copy, create a Maven settings.xml file with your OSSRH credentials and
    your GPG key passphrase:
    ```sh
    SONATYPE_USERNAME="your_sonatype.org_username_here"
    SONATYPE_PASSWORD="your_sonatype.org_password_here"
    GPG_PASSPHRASE="your_gpg_passphrase_here"
    cat > settings.xml