Project import generated by Copybara. PiperOrigin-RevId: 264599919 Change-Id: I1bcf714da804da87819a4944203fcd7a5b06062d
diff --git a/docs/behind-the-release.md b/docs/behind-the-release.md new file mode 100644 index 0000000..80bb89b --- /dev/null +++ b/docs/behind-the-release.md
@@ -0,0 +1,152 @@ +# Behind the Release Process + +## What is a `java_tools` zip? + +A `java_tools` zip is an archive that contains the tools required by Bazel for +building Java targets (e.g. `JavaBuilder`, `Turbine`, `TestRunner`, `ijar`, +`singlejar`, `javac`). Each tool, except `ijar`, `singlejar` and `javac`, are +built from bazel @ HEAD and their deploy jars are archived in `java_tools.zip`. +These deploy jars are platform independent. + +`ijar` and `singlejar` are C++ binaries which are also built from bazel @ HEAD. +The built binaries accompanied by their sources are archived into the +`java_tools` zip. The C++ binaries are platform dependent. + +`java_tools` archive two javac jars: `java_compiler.jar` and `jdk_compiler.jar`. + +## How is a java_tools zip versioned and named? + +### javac version + +The javac version archived into a `java_tools` zip is reflected in the zip’s +name. For example if a `java_tools` zip contains `java_compiler.jar` and +`jdk_compiler.jar` compiled for javac 9, the `java_tools` name contains `javac9`. + +### platform name + +The `java_tools` zip is built individually for every supported platform (Ubuntu, +Windows, MacOS) because the ijar and singlejar C++ binaries are platform +dependent. The platform name is reflected into a `java_tools` version. +For example a `java_tools` zip with binaries built on Windows contains `windows` +in its name. + +### version + +A `java_tools` zip has multiple versions for a certain javac version and platform. +A new `java_tools` version is released when a new feature/bug fix is added. The +version is reflected in the release name. +For example the first version contains `v1.0` and a patch release version can be +`v3.2`. + +## Supported javac versions + +Currently there are `java_tools` releases with embedded `javac` 9, 10, 11, 12. + +## Testing java_tools before the release process + +Each `java_tools` zip contains a `java_toolchain` (`//:toolchain`) in its `BUILD` +file. There are java integration tests that run bazel with `--java_toolchain` +and `--host_java_toolchain` pointing to a `java_tools` zip built at HEAD for +each supported javac version. +The tests are defined in [src/test/shell/bazel/BUILD](https://github.com/bazelbuild/bazel/blob/master/src/test/shell/bazel/BUILD) +(`bazel_java_test_jdk` + `$java_version` + `toolchain_head`). The tests run on +Bazel’s CI presubmit and postbumit. + +## Manually trying out java_tools before the release process + +Build a `java_tools` zip with version *X* by running + +``` +bazel build //src:java_tools_javaX.zip +``` + +Define a repository named `local_java_tools` that points to the built zip. For +example: + +``` +http_archive( + name = "local_java_tools", + urls = ["file///path/to/the/java_tools/zip"] +) +``` + +Build any java target pointing `--java_toolchain/--host_java_toolchain` to +`@local_java_tools//:toolchain`. + +## java_tools binaries pipeline + +The [java_tools binaries pipeline](https://buildkite.com/bazel-trusted/java-tools-binaries-java) +is a Bazel’s Buildkite trusted pipeline. One needs special permission to access +it. If you want to release the Java tools but don’t have these permissions +please contact the Bazel EngProd team (`bazel-engprod@google.com`). + +The configuration file is +[`java_tools-binaries.yml`](https://github.com/bazelbuild/continuous-integration/blob/master/pipelines/java_tools-binaries.yml) +and is maintained by Bazel’s EngProd team. + +Once triggered the pipeline starts independent builds on 3 platforms: Centos7, +Windows 10 and MacOS. Each platform build invokes +[`src/upload_all_java_tools.sh`](https://github.com/bazelbuild/bazel/blob/master/src/upload_all_java_tools.sh), +which does the following: + +1. Builds `java_tools` zips for each supported java version (9, 10, 11, 12). +2. Runs the java integration tests using the `java_toolchain` in each generated `java_tools`. +3. If all tests are successful uploads each `java_tools` zip to GCP (via +[src/upload_java_tools.sh](https://github.com/bazelbuild/bazel/blob/master/src/upload_java_tools.sh)). +The zips are uploaded under +[bazel-mirror/bazel_java_tools/tmp/build](https://console.cloud.google.com/storage/browser/bazel-mirror/bazel_java_tools/tmp/build) +to a file defined by: the commit hash where the tools were built, the javac version, the platform and the timestamp when they were uploaded: + +``` +bazel-mirror/bazel_java_tools/tmp/build/${commit_hash}/java${java_version}/java_tools_javac${java_version}_${platform}-${timestamp}.zip +``` + +## Releasing + +Both creating a release candidate and creating a release use the same script +[`src/create_java_tools_release.sh`](https://github.com/bazelbuild/bazel/blob/master/src/create_java_tools_release.sh). +In both cases the script needs to know: + +- the javac version archived in the wanted RC/release +- the version number of the java_tools to be released +- the release candidate number (either to be created or to be released) +- the commit hash where the zip was built +- a boolean telling whether it’s creating a release candidate or a release + +### Creating a release candidate + +To create a release candidate invoke the [`src/create_java_tools_release.sh`](https://github.com/bazelbuild/bazel/blob/master/src/create_java_tools_release.sh) +script with the parameters set accordingly to the way described above in the +*Releasing* section. + +When creating release candidates the script assumes that the `java_tools` pipeline +was already run at the same commit hash passed to the script. + +The script identifies where the `java_tools` zip was uploaded on GCP by the +`java_tools` pipeline and copy it under a [GCP `release_candidates` directory](https://console.cloud.google.com/storage/browser/bazel-mirror/bazel_java_tools/release_candidates/): + +``` +release_candidates/javac${java_version}/v${java_tools_version}/java_tools_javac${java_version}_${platform}-v${java_tools_version}-rc${rc}.zip +``` + +The uploaded file is the new release candidate. Bazel can be tested by updating +the `java_tools` urls and checksums to the new RC url and its checksum. + + +### Creating a release + +To create a release invoke the [`src/create_java_tools_release.sh`](https://github.com/bazelbuild/bazel/blob/master/src/create_java_tools_release.sh) +script with the parameters set accordingly to the way described above in the +*Releasing* section. When creating releases the script assumes that a release +candidate with the given number was previously created by the script. + +The script identifies where the release candidate with the given number was +uploaded on GCP and copy it under a [GCP `releases` directory](https://console.cloud.google.com/storage/browser/bazel-mirror/bazel_java_tools/releases/): + +``` +releases/javac${java_version}/v${java_tools_version}/java_tools_javac${java_version}_${platform}-v${java_tools_version}-rc${rc}.zip +``` + +The uploaded file is the new release. Bazel can be updated to use new release by +updating the `java_tools` urls and checksums to the new release. +
diff --git a/docs/release.md b/docs/release.md new file mode 100644 index 0000000..ecdd2d2 --- /dev/null +++ b/docs/release.md
@@ -0,0 +1,57 @@ +# Release Process + +*Note: This document describes how to release java_tools for a JDK version that +is already tested by Bazel. This document is addressed to trusted members of +the Bazel team who have access to the Buildkite Bazel trusted pipelines and GCP. +If you want to release the Java tools but don’t have these permissions please +contact someone from the Bazel EngProd team (bazel-engprod@google.com).* + +The steps below are only meant to be followed as presented in order to release +a new java_tools version. To understand the mechanism behind these steps and for +more details about how the process works, see +[Behind the java_tools release process](behind-the-release.md). + +1. Create a new tracking issue for the release in this repository and add the +`release` label. See [#7](https://github.com/bazelbuild/java_tools/issues/7) as +an example. +2. Trigger a new build of the [`java_tools binaries pipeline`](https://buildkite.com/bazel-trusted/java-tools-binaries-java). +3. Identify and set the following environment variables: + + * `COMMIT_HASH` the commit hash where the pipeline was run (see below) + * `JDK_VERSION` the JDK version for which you want to release `java_tools` + * `NEW_VERSION` the new version number you’re trying to release (e.g. `3.1`) + * `RC` the number of the current release candidate + +4. Create a new release candidate by running the command below from the bazel repo: + + ``` + src/create_java_tools_release.sh \ + --commit_hash $COMMIT_HASH \ + --java_tools_version $NEW_VERSION \ + --java_version $JDK_VERSION \ + --rc $RC --release false + ``` + + The script will output the sha256sum of the rc artifacts for linux, darwin + and windows. + +5. Create a new bazel Pull Request that updates the `java_tools` `html_archive`s +with the new release candidates. See +[#8302](https://github.com/bazelbuild/bazel/pull/8302) as an example. +The PR triggers the CI presubmit. + + 1. If the CI finishes successfully: + - create the release artifacts from the + release candidate: + ``` + src/create_java_tools_release.sh \ + --java_tools_version $NEW_VERSION \ + --java_version $JDK_VERSION \ + --rc $RC --release true + ``` + - update the urls of the `http_archive`s in the upgrade PR and send it for + review. + 2. If the CI finishes unsuccessfully find the reasons why the CI is failing + and file bugs. After the bugs are fixed start all over again creating the + next release candidate. This case is highly unlikely because bazel already + tests the `java_tools` built at head.