Release process

Azure SDK for Java release process

The goal of this document is to create an outline of the release process for the Azure SDK for Java team. It is meant to act as general guidelines and ordering of steps needed to be taking during a release cycle.

Before release

Before triggering the release pipeline a PR must be submitted to update the CHANGELOG and README for each module being released. The CHANGELOG's latest release tag needs to be updated to match the releasing library version and the date it is being released. The README's Include the package section needs to be updated to list the version of the library being released, in addition to that this is a good time to do a quick review of the README for typos and other grammatical mistakes.

After the PR has been merged you'll need to validate that all upstream releases are complete, refer to the release order to view the release hierarchy.

Release tracking

Following is the list of updates that is required to be done by package owners to indicate the release status of their respective libraries. Look for your respective package named Java <package-name> from the All-Up<Month-Name> query here.

1. Mark the state to Active indicating the package is part of the monthly release. Mark it as Not in release if it isn't a part of this release cycle.

Navigate to the SDK Release tab on the right to update the following:

1. Ensure the release work item is correctly assigned to the package owner. If your package has a second contact, make sure to assign it to the "Contact 2" field
2. Set a tentative Planned Release Date depending on core and identity release dates.
3. Select the appropriate Release Type.
4. Add the Version Number.

Releasing via pipelines

Once all release prerequisites are met you can manually trigger the respective release pipeline named java - <servicename>. This pipeline then generates the package artifacts and requests for validation approval. Once the generated artifacts are validated, the release is approved to publish the artifacts on Maven.

Post-release

Each package release generates a docs PR here that is to be reviewed and merged by the package owner.

Release order

Release order is based on dependency ordering, therefore when releasing a library you must wait for upstream to release and merge in their version increment PR. There is a caveat when an upstream library is doing a beta release but the downstream library is doing a GA, in this scenario the dependent library will maintain a dependency on the latest GA release of the dependency library and may also ship ahead of upstream (or at the same time).

NOTE: It is safe for the version in the downstream library to increment to the release version as we test this scenario during every PR validation and during the nightly test runs. The From Source pipeline is the one that validates this.

The Azure SDKs for Java uses the following release order.

1. Core libraries

The Azure Core libraries are the root dependency which all other libraries are building on top, this MUST be the first libraries shipped.

2. Identity

Azure Identity is another common dependency that should ship after Azure Core and SHOULD ship before everything else. Identity is a loose requirement here as there are special rules where Identity cannot be included as an explicit dependency and is completely optional based on the consumers discretion.

3. Everything without another library as an upstream dependency

This is the bulk of the Azure SDK libraries, once Core has shipped and the release version is taken these libraries may ship at will. These don't include dependencies on other libraries outside of their library group (Storage libraries share a common library but all will be shipped at once).

Example: Text Analytics, Form Recognizer, Storage, Service Bus

4. Anything with another library as an upstream dependency

These are the last libraries to ship as they contain another non-Core library as a dependency. An example of this is EventHubs Checkpoint Store Blobs which has a dependency on Azure Storage Blobs. This must wait for Azure Storage Blobs to release to prevent any diamond dependency issues such as it and Blobs having different Azure Core dependencies.

Example: Eventhubs - Needs storage packages to be released first

5. Multi release (Beta and GA) release for libraries

For such releases, make sure to follow the branching strategy mentioned here for easier release.

These are the libraries that have GA and feature/beta releases happening in the same release cycle. In these cases, the release for GA libraries should still follow the above 1-4 release ordering strategy and should be released first. And the beta releases should take place after all the other monthly releases have completed. These beta/feature branches should have the latest master dependencies correctly pulled in. All such beta releases will still have to follow the release ordering of 1-4 for resolving library dependencies.