11# Releasing TensorFlow Java
22
33The
4- [ TensorFlow Java API] ( https://github.com/tensorflow/java ) is available on Maven Central and JCenter
4+ [ TensorFlow Java API] ( https://github.com/tensorflow/java ) is available on Maven Central
55through artifacts uploaded to
6- [ OSS Sonatype ] ( https://oss .sonatype.org/content/repositories/releases/org/tensorflow / ) . This
6+ [ Maven Central ] ( https://central .sonatype.com / ) . This
77document describes the process of updating the release artifacts. It does _ not_ describe how to use
88the artifacts, for which the reader is referred to the
99[ TensorFlow for Java installation instructions] ( https://github.com/tensorflow/java/blob/master/README.md ) .
@@ -14,8 +14,7 @@ TensorFlow source (which is primarily in C++) is built using
1414[ bazel] ( https://bazel.build ) and not [ maven] ( https://maven.apache.org/ ) . TensorFlow Java
1515wraps over this native code and thus depends on platform (OS, architecture) specific native code.
1616
17- Hence, the process for building and uploading release artifacts is not a single
18- ` mvn deploy ` command.
17+ Hence, the process for building and uploading release artifacts is not a single ` mvn deploy ` command.
1918
2019## Release process overview
2120
@@ -24,23 +23,30 @@ The process of releasing TensorFlow Java is split in two major steps:
2423* Building and deploying all artifacts consolidated
2524
2625The 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.
26+ artifact for a specific architecture and platform. The second step retrieves all native artifacts
27+ built in the first step to consolidate them on a single server, and run a Maven ` deploy ` from there.
2928
3029It is important to note that any change pushed to a release branch (i.e. a branch prefixed
3130by ` r ` ) will start a new release workflow. Therefore, these changes should always increment the
3231version number.
3332
3433### Pre-requisites
3534
36- - ` docker `
37- - An account at [ oss.sonatype.org] ( https://oss.sonatype.org/ ) , that has
35+ - An account at [ Maven Central] ( https://central.sonatype.com/ ) , that has
3836 permissions to update artifacts in the ` org.tensorflow ` group. If your
3937 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 ) .
38+ to [ file a ticket] ( mailto:central-support@sonatype.com ) to add to the permissions.
39+ -
40+ Add your account username and token to the GitHub repository secrets as `CI_DEPLOY_USERNAME` and `CI_DEPLOY_PASSWORD`
41+ respectively.
42+
43+ - A [ GPG signing key] ( http://central.sonatype.org/pages/apache-maven.html#gpg-signed-components ) for signing the artifacts.
44+
45+ The public key must be registered with a key server supported by Maven Central (e.g. https://keyserver.ubuntu.com/ ) and
46+ the private key + passphrase should be stored in the GitHub repository secrets as ` MAVEN_GPG_PRIVATE_KEY ` and
47+ ` MAVEN_GPG_PASSPHRASE ` respectively. See [ GitHub documentation] ( https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#Publishing-using-Apache-Maven )
48+ for more details.
49+
4450
4551### Preparing a release
4652
@@ -60,10 +66,10 @@ version number.
6066 mvn versions:set -DnewVersion=1.0.0
6167 ```
62684. Update the TensorFlow Java version to reflect the new release at the following locations:
63- - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L61
64- - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L167
69+ - https://github.com/tensorflow/java/blob/master/docs/docs/ install.md?plain=1#L69
70+ - https://github.com/tensorflow/java/blob/master/docs/docs/ install.md?plain=1#L175
6571 - https://github.com/tensorflow/java/blob/master/README.md#using-maven-artifacts
66- - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-version-support
72+ - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-java- version-support
6773
68745. Commit the changes and push the new branch to the GitHub repository
6975 ```
@@ -91,10 +97,10 @@ version number.
9197 mvn versions:set -DnewVersion=1.0.1
9298 ```
93995. Update the TensorFlow Java version to reflect the new release at the following locations:
94- - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L61
95- - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L167
100+ - https://github.com/tensorflow/java/blob/master/docs/docs/ install.md?plain=1#L69
101+ - https://github.com/tensorflow/java/blob/master/docs/docs/ install.md?plain=1#L175
96102 - https://github.com/tensorflow/java/blob/master/README.md#using-maven-artifacts
97- - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-version-support
103+ - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-java- version-support
98104
991056. Commit the changes and push the branch to the GitHub repository
100106 ```
@@ -103,86 +109,33 @@ version number.
103109 git push
104110 ```
105111
106- ### Building native artifacts
107-
108- Any change pushed to a release branch will trigger a new release workflow. GitHub Actions builds the native artifacts
109- for all supported architures/platforms and deploy them temporarily on OSSRH for staging.
110-
111- There is no user action required for this step other than watching the progress of the GitHub
112- Actions workflow and making sure that all steps have been completed successfully.
113-
114- #### Build native artifacts manually
115-
116- Some platforms cannot be build successfully on GitHub Actions, due to some limits to their resources
117- (e.g. max 6 hours for a job). For this reasons, we need to build manually some of our artifacts on
118- private servers.
119-
120- To do so, follow the same steps as the [CI build](https://github.com/tensorflow/java/blob/master/.github/workflows/ci.yml)
121- for the same platform and make sure to checkout the release branch and to provide your Sonatype credentials
122- for temporary staging.
123-
124- ### Performing the release
125-
126- 1. At the root of your TensorFlow Java copy, create a Maven settings.xml file with your OSSRH credentials and
127- your GPG key passphrase:
128- ```sh
129- SONATYPE_USERNAME="your_sonatype.org_username_here"
130- SONATYPE_PASSWORD="your_sonatype.org_password_here"
131- GPG_PASSPHRASE="your_gpg_passphrase_here"
132- cat > settings.xml <<EOF
133- <settings>
134- <servers>
135- <server>
136- <id>central</id>
137- <username>${USERNAME}</username>
138- <password>${PASSWORD}</password>
139- </server>
140- <server>
141- <id>central-staging</id>
142- <username>${USERNAME}</username>
143- <password>${PASSWORD}</password>
144- </server>
145- </servers>
146- <profiles>
147- <profile>
148- <activation>
149- <activeByDefault>true</activeByDefault>
150- </activation>
151- <properties>
152- <gpg.executable>gpg2</gpg.executable>
153- <gpg.passphrase>${GPG_PASSPHRASE}</gpg.passphrase>
154- </properties>
155- </profile>
156- <profiles>
157- </settings>
158- EOF
159- ```
160- 2. Execute the `release.sh` script. This will deploy artifacts on OSS Sonatype. All native artifacts
161- previously temporarily staged by GitHub Actions will be fetched, signed and redeployed as well.
162-
163- The script takes in a parameter the sequence number of the staging repository created in OSSRH
164- by the GitHub Actions workflow. You can retrieve this ID by looking in the staging repositories
165- in OSSRH console directly, or check at the output of the step `Create Staging Repository` of the
166- `prepare` job in the workflow execution, where the ID is printed.
167- ```
168- # Staging repository created: orgtensorflow-1100
169- sh release.sh 1100
170- ```
171- 3. If the script above succeeds then the artifacts would have been uploaded to
172- the private staging repository in Sonatype. After verifying the release, you should finalize or
173- abort the release. Visit https://oss.sonatype.org/#stagingRepositories, find the `orgtensorflow-*`
174- of your release and click `Close` and `Release` to finalize the release. You always have the option
175- to `Drop` it to abort and restart if something went wrong.
176-
177- 4. Go to GitHub and create a release tag on the release branch with a summary of what the version includes.
178-
179- Some things of note:
180- - For details, look at the [Sonatype guide](http://central.sonatype.org/pages/releasing-the-deployment.html).
181- - Syncing with [Maven Central](http://repo1.maven.org/maven2/org/tensorflow/) can take 10 minutes to 2 hours.
182-
183- ### Finishing a release
112+ ### Performing the Release
184113
185- #### Major or minor release
114+ #### Release Workflow
115+
116+ Pushing on a release branch will trigger a GitHub Actions workflow that builds the native artifacts for all supported architectures/platforms
117+ and deploys them temporarily as GitHub Workflow artifacts.
118+
119+ After this step, all native artifacts are retrieved and consolidated into the same target folder on single server in GitHub Action.
120+ A final Maven `deploy` command on that server will take care of publishing all TensorFlow Java artifacts (include the native ones) to Maven
121+ Central for staging.
122+
123+ #### Publishing Approval
124+
125+ After all artifacts have been published, you should log to [Maven Central](https://central.sonatype.com/), go to `Publish -> Deployments`,
126+ and either drop the staging repository (if something is wrong) or publish it (if everything looks good). If you drop it, you will need to
127+ retrigger the [release CI](#release-workflow).
128+
129+ ### Finishing a Release
130+
131+ #### Release Notes
132+
133+ Go to GitHub and automatically generate release notes for the new version by going to `Releases -> Draft a new release`
134+ and selecting the tag for the release. You can edit the release notes as needed.
135+
136+ #### Bumping Next Snapshot Version
137+
138+ ##### After a Major or Minor Release
186139
1871401. Checkout the master branch and merge back changes from the released branch
188141 ```
@@ -194,9 +147,9 @@ Some things of note:
194147 mvn versions: set -DnewVersion=1.3.0-SNAPSHOT
195148 ```
1961493. Update the TensorFlow Java version to reflect the new snapshot at the following locations:
197- - https://github.com/tensorflow/java/blob/master/docs/install.md?plain=1#L104
150+ - https://github.com/tensorflow/java/blob/master/docs/docs/ install.md?plain=1#L112
198151 - https://github.com/tensorflow/java/blob/master/README.md#using-maven-artifacts
199- - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-version-support
152+ - https://github.com/tensorflow/java/blob/master/README.md#tensorflow-java- version-support
200153
2011544. Commit your changes and push the master branch to the GitHub repository
202155 ```
@@ -205,7 +158,7 @@ Some things of note:
205158 git push
206159 ```
207160
208- #### Patch release
161+ ##### After a Patch Release
209162
2101631. Checkout the master branch and merge back changes from the released branch
211164 ```
0 commit comments