Release process

Azure SDK for Java release process

This document outlines the Azure SDK for Java team's release process. It's a general guideline and the ordering of steps taken during a release cycle.

Prepare for release

Update the current-version of the package being released

1. Change the current-version listed in version_client.txt.
2. Run the update_versions.py script.

NOTE: This is only needed if the current-version in version_client.txt file differs from the version being released.

For further details about this, you can find more information here and here. This azure-core PR is an example of preparing for release.

Update the CHANGELOG and README

1. Change the CHANGELOG's unreleased tag to match the version being released and the date being released.
2. Add highlights for the release in the CHANGELOG section using this guideline.
3. Update the README's Include the package section to list the version of the library being released.

Await release GO email

Once version, CHANGELOG, and README updates have been merged you'll need to wait until all upstream releases are completed. A release hierarchy is used to ensure that versions align, refer to the release order to view the release hierarchy.

If you have dependency issues/questions reach out to the release manager ahead of time. As releases complete the release manager will send out "GO" emails updating the status of release and which packages can begin releasing at the time of email. You should be on the azure-sdk-for-java GitHub Repo Area Owners [email protected] mailing group to receive these emails.

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.

1. Look for a pipeline named java - <packagename> 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 version 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.