[Feature Request]: Modules API version update criteria

[eriqua]

Description

The context

Static validation: Pester tests aim to ensure each module leverages an API version which is "recent enough", not older than the latest e.g. X released versions.

Module readme: documentation aims to ensure each used API version is tracked and linked to the official corresponding documentation in the Azure Resource Reference.

The problem

The Azure Resource Reference is often not up-to-date and sometimes completely lacking documentation for certain resource types.

When checking the right API version to choose for a resource type, we often fall into the discussion of which latest version we should consider: if the latest stable released or if the latest documented by the Azure Resource Reference. See for instance discussion in PR #1662

In general, we must avoid providing a wrong documentation, i.e. linking a documentation from the Azure Resource Reference which is not corresponding to the one used by the modules. This is currently the case for some resources.

Acceptance criteria

This issue is about

• discussing and agreeing on the criteria to follow when updating an API version/implementing a new module
• documenting the decision in the wiki
• the decision may impact either the Pester tests logic or the readme API version documentation to provide, for which separated issues will be opened.

[eriqua]

Additional note after merging PR #1662.

The resource reference does not have a unique documentation for the Microsoft.Web staticSites/config resource under the latest API version. It instead provides two, based on the name value: https://learn.microsoft.com/en-us/azure/templates/microsoft.web/2022-03-01/staticsites/config-appsettings?pivots=deployment-language-bicep and https://learn.microsoft.com/en-us/azure/templates/microsoft.web/2022-03-01/staticsites/config-functionappsettings?pivots=deployment-language-bicep.

This is an exception to how the link to the ARR for a specific resource type is build by the readme generator script. For how the readme generator works, we're now pointing to this link instead https://learn.microsoft.com/en-us/azure/templates/microsoft.web/staticsites/config which is misleading since it refers to API version 2020-10-01, whilst the one used in the module is 2022-03-01.

Ref Microsoft.Web/staticSites readme

CC @mrmcake, @itpropro

[rahalan]

Team decides: If there is not matching Link in the Azure Resource Reference, provide at least latest
A comment to the link should be added, if the version is not existing
ToDo: propose the exact wording before implementing to the team