|
| 1 | +# Releasing TensorFlow Java |
| 2 | + |
| 3 | +The |
| 4 | +[TensorFlow Java API](https://github.com/tensorflow/java) is available on Maven Central and JCenter |
| 5 | +through artifacts uploaded to |
| 6 | +[OSS Sonatype](https://oss.sonatype.org/content/repositories/releases/org/tensorflow/). This |
| 7 | +document describes the process of updating the release artifacts. It does _not_ describe how to use |
| 8 | +the artifacts, for which the reader is referred to the |
| 9 | +[TensorFlow for Java installation instructions](https://github.com/tensorflow/java/blob/master/README.md). |
| 10 | + |
| 11 | +## Background |
| 12 | + |
| 13 | +TensorFlow source (which is primarily in C++) is built using |
| 14 | +[bazel](https://bazel.build) and not [maven](https://maven.apache.org/). TensorFlow Java |
| 15 | +wraps over this native code and thus depends on platform (OS, architecture) specific native code. |
| 16 | + |
| 17 | +Hence, the process for building and uploading release artifacts is not a single |
| 18 | +`mvn deploy` command. |
| 19 | + |
| 20 | +## Release process overview |
| 21 | + |
| 22 | +The process of releasing TensorFlow Java is split in two major steps: |
| 23 | +* Building and deploying the native artifacts |
| 24 | +* Building and deploying all artifacts consolidated |
| 25 | + |
| 26 | +The first step is executed on different build servers, each responsible to build the native |
| 27 | +artifact for a specific architecture and platform. The second step is conducted locally in |
| 28 | +a [Docker](https://www.docker.com) container for a hermetic release process. |
| 29 | + |
| 30 | +It is important to note that any change pushed to a release branch (i.e. a branch prefixed |
| 31 | +by `r`) will start a new release workflow. Therefore, these changes should always increment the |
| 32 | +version number. |
| 33 | + |
| 34 | +### Pre-requisites |
| 35 | + |
| 36 | +- `docker` |
| 37 | +- An account at [oss.sonatype.org](https://oss.sonatype.org/), that has |
| 38 | + permissions to update artifacts in the `org.tensorflow` group. If your |
| 39 | + account does not have permissions, then you'll need to ask someone who does |
| 40 | + to [file a ticket](https://issues.sonatype.org/) to add to the permissions |
| 41 | + ([sample ticket](https://issues.sonatype.org/browse/MVNCENTRAL-1637)). |
| 42 | +- A GPG signing key, required |
| 43 | + [to sign the release artifacts](http://central.sonatype.org/pages/apache-maven.html#gpg-signed-components). |
| 44 | + |
| 45 | +### Preparing a release |
| 46 | + |
| 47 | +#### Major or minor release |
| 48 | + |
| 49 | +1. Get a clean version of the source code by cloning the |
| 50 | + [TensorFlow Java GitHub repository](https://github.com/tensorflow/java) |
| 51 | + ``` |
| 52 | + git clone https://github.com/tensorflow/java |
| 53 | + ``` |
| 54 | +2. Create a new branch for the release named `r<MajorVersion>.<MinorVersion>` |
| 55 | + ``` |
| 56 | + git checkout -b r1.0 |
| 57 | + ``` |
| 58 | +3. Update the version of the Maven artifacts to the full version of the release |
| 59 | + ``` |
| 60 | + mvn versions:set -DnewVersion=1.0.0 |
| 61 | + ``` |
| 62 | +4. Commit the changes and push the new branch to the GitHub repository |
| 63 | + ``` |
| 64 | + git add . |
| 65 | + git commit -m "Releasing 1.0.0" |
| 66 | + git push --set-upstream origin r1.0 |
| 67 | + ``` |
| 68 | +
|
| 69 | +#### Patch release |
| 70 | +
|
| 71 | +1. Get a clean version of the source code by cloning the |
| 72 | + [TensorFlow Java GitHub repository](https://github.com/tensorflow/java) |
| 73 | + ``` |
| 74 | + git clone https://github.com/tensorflow/java |
| 75 | + ``` |
| 76 | +2. Switch to the release branch of the version to patch |
| 77 | + ``` |
| 78 | + git checkout r1.0 |
| 79 | + ``` |
| 80 | +3. Patch the code with your changes. For example, changes could be merged from another branch you |
| 81 | + were working on or be applied directly to this branch when the required changes are minimal. |
| 82 | +
|
| 83 | +4. Update the version of the Maven artifacts to the full version of the release |
| 84 | + ``` |
| 85 | + mvn versions:set -DnewVersion=1.0.1 |
| 86 | + ``` |
| 87 | +4. Commit the changes and push the branch to the GitHub repository |
| 88 | + ``` |
| 89 | + git add . |
| 90 | + git commit -m "Releasing 1.0.1" |
| 91 | + git push |
| 92 | + ``` |
| 93 | +
|
| 94 | +### Building native artifacts |
| 95 | +
|
| 96 | +Any change pushed to a release branch will trigger a new release workflow. GitHub Actions builds the native artifacts |
| 97 | +for all supported architures/platforms and deploy them temporarily on OSSRH for staging. |
| 98 | +
|
| 99 | +There is no user action required for this step other than watching the progress of the GitHub |
| 100 | +Actions workflow and making sure that all steps have been completed successfully. |
| 101 | +
|
| 102 | +#### Build native artifacts manually |
| 103 | +
|
| 104 | +Some platforms cannot be build successfully on GitHub Actions, due to some limits to their resources |
| 105 | +(e.g. max 6 hours for a job). For this reasons, we need to build manually some of our artifacts on |
| 106 | +private servers. |
| 107 | +
|
| 108 | +To do so, follow the same steps as the [CI build](https://github.com/tensorflow/java/blob/master/.github/workflows/ci.yml) |
| 109 | +for the same platform and make sure to checkout the release branch and to provide your Sonatype credentials |
| 110 | +for temporary staging. |
| 111 | +
|
| 112 | +### Building and deploying all artifacts to Sonatype |
| 113 | +
|
| 114 | +1. At the root of your TensorFlow Java copy, create a Maven settings.xml file with your OSSRH credentials and |
| 115 | + your GPG key passphrase: |
| 116 | + ```sh |
| 117 | + SONATYPE_USERNAME="your_sonatype.org_username_here" |
| 118 | + SONATYPE_PASSWORD="your_sonatype.org_password_here" |
| 119 | + GPG_PASSPHRASE="your_gpg_passphrase_here" |
| 120 | + cat > settings.xml <<EOF |
| 121 | + <settings> |
| 122 | + <servers> |
| 123 | + <server> |
| 124 | + <id>ossrh</id> |
| 125 | + <username>${SONATYPE_USERNAME}</username> |
| 126 | + <password>${SONATYPE_PASSWORD}</password> |
| 127 | + </server> |
| 128 | + <server> |
| 129 | + <id>ossrh-staging</id> |
| 130 | + <username>${SONATYPE_USERNAME}</username> |
| 131 | + <password>${SONATYPE_PASSWORD}</password> |
| 132 | + </server> |
| 133 | + </servers> |
| 134 | + <profiles> |
| 135 | + <profile> |
| 136 | + <activation> |
| 137 | + <activeByDefault>true</activeByDefault> |
| 138 | + </activation> |
| 139 | + <properties> |
| 140 | + <gpg.executable>gpg2</gpg.executable> |
| 141 | + <gpg.passphrase>${GPG_PASSPHRASE}</gpg.passphrase> |
| 142 | + </properties> |
| 143 | + </profile> |
| 144 | + <profiles> |
| 145 | + </settings> |
| 146 | + EOF |
| 147 | + ``` |
| 148 | +2. Execute the `release.sh` script. This will deploy artifacts on OSS Sonatype. All native artifacts |
| 149 | + previously temporarily staged by GitHub Actions will be fetched, signed and redeployed as well. |
| 150 | +
|
| 151 | + The script takes in paramater the sequence number of the staging repository created in OSSRH |
| 152 | + by the GitHub Actions workflow. You can retrieve this ID by looking in the staging repositories |
| 153 | + in OSSRH console directly, or check at the output of the step `Create Staging Repository` of the |
| 154 | + `prepare` job in the workflow execution, where the ID is printed. |
| 155 | + ``` |
| 156 | + # Staging repository created: orgtensorflow-1100 |
| 157 | + sh release.sh 1100 |
| 158 | + ``` |
| 159 | +3. If the script above succeeds then the artifacts would have been uploaded to |
| 160 | + the private staging repository in Sonatype. After verifying the release, you should finalize or |
| 161 | + abort the release. Visit https://oss.sonatype.org/#stagingRepositories, find the `orgtensorflow-*` |
| 162 | + of your release and click `Close` and `Release` to finalize the release. You always have the option |
| 163 | + to `Drop` it to abort and restart if something went wrong. |
| 164 | +
|
| 165 | +4. Some things of note: |
| 166 | + - For details, look at the [Sonatype guide](http://central.sonatype.org/pages/releasing-the-deployment.html). |
| 167 | + - Syncing with [Maven Central](http://repo1.maven.org/maven2/org/tensorflow/) |
| 168 | + can take 10 minutes to 2 hours (as per the [OSSRH |
| 169 | + guide](http://central.sonatype.org/pages/ossrh-guide.html#releasing-to-central)). |
| 170 | +
|
| 171 | +### Finishing a release |
| 172 | +
|
| 173 | +Go to GitHub and create a release tag at the release branch with a summary of what the version includes. |
| 174 | +
|
| 175 | +#### Major or minor release |
| 176 | +
|
| 177 | +1. In your local copy, checkout the master branch and increase the next snapshot version. |
| 178 | + ``` |
| 179 | + mvn versions:set -DnewVersion=1.1.0-SNAPSHOT |
| 180 | + ``` |
| 181 | +2. Commit your changes and push the master branch to the GitHub repository |
| 182 | + ``` |
| 183 | + git add . |
| 184 | + git commit -m "Increase version for next iteration" |
| 185 | + git push |
| 186 | + ``` |
| 187 | +
|
| 188 | +## References |
| 189 | +
|
| 190 | +- [Sonatype guide](http://central.sonatype.org/pages/ossrh-guide.html) for |
| 191 | + hosting releases. |
| 192 | +- [Ticket that created the `org/tensorflow` configuration](https://issues.sonatype.org/browse/OSSRH-28072) on OSSRH. |
0 commit comments