BOM Guidelines

Introduction

A "bill of materials" (BOM) is a customer-focused POM that contains a set of modules that are known to share a common set of dependencies. This reduces the need for consumers to handle dependency management for the Azure SDKs included in the BOM and allows more focus on the bigger picture.

azure-sdk-bom may contain modules that haven't reached generally availability (GA), unlike in generally available modules this is allowed as the modules are contained in the dependencyManagement section. Artifacts listed in the management section aren't included as a dependency until listed in the dependencies section of the POM that is including azure-sdk-bom.

Using the BOM

To consume the BOM, add it as an artifact in the dependency management section of the POM consuming it.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>1.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

After including the BOM, all artifacts included in the BOM are now able to be added as a dependency without listing the version.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-secrets</artifactId>
  </dependency>
</dependencies>

Release

A BOM is released to Maven in the same way as an artifact.

Cadence

The release cadence for azure-sdk-bom may not match the cadence which the individual artifacts contained in it are released.

Versioning

The version change for azure-sdk-bom is based on the version changes for the artifacts it contains. The common version update for the BOM will be a patch release, this will occur if the artifacts contained in the BOM only have minor or patch releases. When an artifact contained in the BOM has a major version release the BOM will have a minor version update.

Example

Given the version for azure-sdk-bom is 1.0.0.

Artifact Update	Resulting azure-sdk-bom Version
Major	1.1.0
Minor	1.0.1
Patch	1.0.1

Validation

The validation process for azure-sdk-bom is different from other artifacts where linting and test cases must pass and the dependencies are released to Maven.

Dependency Checker

A BOM must ensure that the artifacts it contains share a common set of dependencies, this is determined by running a dependency checker and validating that no artifacts have conflicting dependencies. The dependency checker is a custom tool, below are the steps to run the tool.

1. Clone the repository: git clone https://github.com/JonathanGiles/DependencyChecker.git
2. Create an input directory in the root directory of the repository.
3. Copy dependencies.json for azure-sdk-bom into the input folder.
4. Run the checker: mvn -f pom.xml clean package exec:java -Dexex.args="-showall -analysebom"
5. Verify the output from the dependency checker run.

The dependency checker output has three output levels:

Output Level	Color	Explanation
Success	Green	All artifacts share a common dependency and the latest version of the dependency is being used.
Warning	Orange	All artifacts share a common dependency but the version of the dependency isn't the latest released to Maven.
Error	Red	Two or more artifacts conflict on the version of a common dependency.

A release candidate for azure-sdk-bom CANNOT have any errors in the output from running the dependency checker.