Adding a Module

This document explains how to add a new client module into the repository.

Overview

Adding a new module to Azure SDKs for Java will require changes to Maven and Azure Pipeline configurations. New modules may be added to an existing group, such as Azure Storage, or be the beginning of a new group; the differences on what needs to be configured will be called out in this document.

Creating the module

If the module is in a new group a new directory will need to be added under sdk/, such as sdk/<new group>.

Begin by adding a new directory in the directory group for the module, such as sdk/<group>/<new module>. The directory name should match the package name sans the starting com, so if the package is com.azure.newservice.newpackage the directory will be azure-newservice-newpackage.

After the directory has been added there are a few required files that must be added, they are the following:

• CHANGELOG.md that follows the changelog guideline.
• pom.xml that uses sdk/parents/azure-client-sdk-parent/pom.xml as its parent POM.
• README.md that uses the README template.
• src directory containing the Java code for the module.

Failing to follow the CHANGELOG or README specifications may result in PR validation failures as there are validation steps which ensure guidelines are met.

Group Changes

Parent POM Changes

Parent pom in sdk/parents/azure-client-sdk-parent serves as a parent POM to all client modules in the repository. Changes made to this file will be the same when adding a new module to an existing group or creating a new group.

Adding to modules configuration

Begin by adding your new modules into the modules configuration section of the pom.xml found in the root of the repository, this should be added based on the alphabetical sorting of your new module. This will ensure that your module is loaded when the pom.xml project is opened in IDEs such as IntelliJ and that is it built during aggregate Maven lifecycle steps.

<modules>
  <!-- existing modules sorted alphabetically before your module -->
  <module>path to your module's pom.xml directory</module>
  <!-- existing modules sorted alphabetically after your module -->
</modules>

Adding to Javadoc generation

Adding to codesnippets generation

Refer to JavaDoc with codesnippet wiki.

Aggregate POM Changes

Azure SDKs for Java contains a few POM files which are used as aggregators for running linting and code coverage tools such as SpotBugs and Jacoco code coverage.

Versioning Management

Miscellaneous Changes

There are additional, but optional, changes that may be required when setting up a new module.

Suppressing Swagger transform README failures

During PR validation a script will run to ensure that all README.md files contained within the repository match a given structure. If your new module leverages code generation the README file which contains the AutoRest configuration and Swagger transforms won't, nor should, comply with this structure. An entry will need to be added to docsettings configuration file in the known_content_issues section to suppress this file from failing PR validation.

Configuring CODEOWNERS

If a new module group is being added, which requires adding a new sub-folder directory, you'll want to add a new entry to CODEOWNERS. This allows GitHub to automatically assign the specified users as reviewers to all PRs opened against the new module group.

Common Issues

This section will outline commonly ran into issues when setting up a new module and outline how to resolve them.

Examples

Adding a new module to the Azure Core group

In this example we are adding a new module Azure Core MQTT which contains all commonly used functionality for the MQTT protocol, akin to Azure Core AMQP.

pom.client.xml changes

Group configuration changes

Ancillary changes

Adding a new module to a new group

In this example we are adding a new module Azure New Service which is the beginning of a new SDK group.

pom.client.xml changes

Creating the group

Ancillary changes