Bicep Utility Module Specifications

ID: BCPNFR14 - Category: Composition - Versioning

To meet SNFR17 and depending on the changes you make, you may need to bump the version in the version.json file.

  {
    "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#",
    "version": "0.1",
    "pathFilters": [
        "./main.json"
    ]
  }
  

The version value is in the form of MAJOR.MINOR. The PATCH version will be incremented by the CI automatically when publishing the module to the Public Bicep Registry once the corresponding pull request is merged. Therefore, contributions that would only require an update of the patch version, can keep the version.json file intact.

For example, the version value should be:

• 0.1 for new modules, so that they can be released as v0.1.0.
• 1.0 once the module owner signs off the module is stable enough for it’s first Major release of v1.0.0.
• 0.x for all feature updates between the first release v0.1.0 and the first Major release of v1.0.0.

ID: SNFR17 - Category: Release - Semantic Versioning

Modules MUST use semantic versioning (aka semver) for their versions and releases in accordance with: Semantic Versioning 2.0.0

For example all modules should be released using a semantic version that matches this pattern: X.Y.Z

• X == Major Version
• Y == Minor Version
• Z == Patch Version

Module versioning before first Major version release 1.0.0

• Initially modules MUST be released as version 0.1.0 and incremented via Minor and Patch versions only until the AVM Core Team are confident the AVM specifications are mature enough and appropriate CI test coverage is in place, plus the module owner is happy the module has been “road tested” and is now stable enough for its first Major release of version 1.0.0.

  Note

  Releasing as version 0.1.0 initially and only incrementing Minor and Patch versions allows the module owner to make breaking changes more easily and frequently as it’s still not an official Major/Stable release. 👍

• Until first Major version 1.0.0 is released, given a version number X.Y.Z:

  • X Major version MUST NOT be bumped.
  • Y Minor version MUST be bumped when introducing breaking changes (which would normally bump Major after 1.0.0 release) or feature updates (same as it will be after 1.0.0 release).
  • Z Patch version MUST be bumped when introducing non-breaking, backward compatible bug fixes (same as it will be after 1.0.0 release).

ID: BCPNRF22 - Category: Publishing - Changelog

When a module to be published (i.e., that has a version.json file) is changed, an entry MUST be created in the CHANGELOG.md file in the module folder.

For each new version, an entry MUST be created above all existing versions in the CHANGELOG.md file of the module.

## <version>

### Changes

- this changed
- and this also

### Breaking Changes

- none

Each version’s entry MUST contain two sections: Changes and Breaking Changes. At least one of them must have a meaningful entry and sections must not be left empty. A - none may be added as content for a section.

Example content of the CHANGELOG.md

A CHANGELOG.md file in the module’s root folder MUST start with the # Changelog header, followed by an empty line. A section for each published version follows. Newer versions are placed above older versions.

# Changelog

## 0.2.1

### Changes

- Updated the referenced AVM common types

### Breaking Changes

- none

## 0.2.0

### Changes

- Implemented the minCPU parameter
- Updated the referenced VirtualNetwork module
- Updated the referenced AVM common types

### Breaking Changes

- The minCPU parameter is mandatory

## 0.1.0

### Changes

- Initial Release

### Breaking Changes

- none

Manual Editing

It is possible to modify the changelog content any time, e.g., to add missing versions. Please note the following requirements in all cases:

• all versions in the file, need to be valid and available as published version
• every version needs the two sections ## Changes and ## Breaking Changes with content