Providing the Spring ecosystem with a first-class experience is of the utmost importance. The guidelines below are in addition to the standard Java design guidelines, overriding the guidance as appropriate.

Namespaces

DO ensure all Java packages are named using the form com.azure.spring.<group>.<service>[.<feature>].

DO use the same group, service, and feature naming as is used by the underlying Java client library.

DO put all non-public API under an implementation package under the root namespace.

Maven

DO use the group ID of com.azure.spring.

DO specify the artifactId to be of the form azure-spring-boot-starter-<group>-<service>[-<feature>], for example, azure-spring-boot-starter-storage-blob or azure-spring-boot-starter-security-keyvault-secrets. For Spring data abstraction, the artifactId should be of the form azure-spring-data-<group>-<service>[-<feature>]. For Spring cloud starters, the artifactId should be of the form azure-spring-cloud-starter-<group>-<service>[-<feature>].

DO include a dependencyManagement dependency on the Azure Java SDK BOM, so that users who use Azure Spring libraries can bring in additional dependencies on other Azure Java client libraries without needing to choose versions.

Versioning

Spring integration modules must be versioned in a way that enables the following goals:

  1. Each Spring integration module must be able to release at different release cadences.
  2. Each Spring integration module must have full semantic versioning for major, minor, and patch versions, in all releases. Versioning must not be tied to the Spring dependency version as in earlier iterations of the Azure Spring integration modules.
  3. Allow developers to easily choose Spring integration modules which work together.

DO ensure that all releases of a Spring integration module support all active versions (as of the time of release) of the corresponding Spring API.

DO add latest release version of Spring API dependencies in the Spring integration module POM files, it is the users responsibility to override the Spring API version via Spring BOM.

DO add Maven classifiers to releases if a Spring integration module cannot support all active versions of the corresponding Spring API. For example, if a Spring integration module needs to support Spring Boot 2.2.x and 2.3.x, but cannot due to technical contraints, two versions of the Spring integration module must be released, with classifiers springboot_2_2 and springboot_2_3.

DO provide a Spring integration modules BOM for users. This BOM must contain versions of all Spring integration modules that are known to work together (and have a single set of dependency versions). It must also include appropriate references to Azure Java SDK.

DO encourage users to use the Spring integration modules BOM for their chosen version of Spring rather than specific versions of each Spring integration module, such that they need not worry about Maven classifiers and other versioning issues.

Dependencies

⛔️ DO NOT introduce dependencies on libraries, or change dependency versions, without discussion with the Java architect. Each dependency must receive explicit approval and be added to the dependency allow list before it may be used.

⛔️ DO NOT introduce dependencies on library versions that conflict with the transitive dependencies of Spring libraries.

DO make use of com.azure client libraries only - do not mix older com.microsoft.azure client libraries into the dependency hierarchy.

DO keep dependencies to the minimal required set.

Logging

⛔️ DO NOT use the ClientLogger logging APIs.

Tracing

DO ensure that all Azure Spring libraries fully integrate with the tracing capabilities available in the Azure Java client libraries.

DO ensure that all Azure Spring libraries work appropriately with Spring Sleuth, and that tracing information is appropriately exported.

Performance

DO ensure, through appropriate benchmarks (developed in conjuction with the Java SDK team) that performance of all Spring libraries is at an equivalent level to the same operation being performed directly through the Java client library.