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.

Prepare for release

1. Create a PR to update the current-version of the package to be released on the version_client.txt file and run the update_versions.py script. This is only needed if the current-version in the version_client.txt file is different from the one you want to release.

   • Here you can find more detailed information on this process.
   • An example of how the "prepare for release" looks like for azure-core.
   • Look here, for more info on versions and versioning.

2. 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. Make sure to follow the highlighting policies for including key changes as mentioned here.

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. Do reach out to the release manager in charge for any curious dependency issues that need to be sorted ahead of time. Look out for a "GO" email sent by the release manager indicating the specific release ordering for packages.

Release tracking Devops

Following is the list of updates that are required to be done by the package owners to indicate the release status of their respective libraries being released. Look for the 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 the above release prerequisites are met you need to manually trigger the release for your respective package pipeline. Look for a pipeline named java - <servicename> here. 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

1. The package owner should approve and merge the generated increment PR, example.
2. The package owner should approve and merge the generated docs PR here for their respective packages.

Please refer to Release Process policies for more information on the release guidelines or reach to the Release channel on teams for any further questions.

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 that 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 consumer's 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.