search

Azure / Azure-Verified-Modules

Azure Verified Modules (AVM) is an initiative to consolidate and set the standards for what a good Infrastructure-as-Code module looks like. Modules will then align to these standards, across languages (Bicep, Terraform etc.) and will then be classified as AVMs and available from their respective language specific registries.
https://aka.ms/AVM
MIT License
317 stars 65 forks source link

[Question/Feedback]: Publish versioned module README as documentation #959

Open o-l-a-v opened 3 months ago

o-l-a-v commented 3 months ago

Check for previous/existing GitHub issues

Description

Feature request

Publish versioned module/resource READMEs as documentation.

Context

Bicep module for App Service Plan is v0.2 in GitHub, but newest in Bicep registry is 0.1.1. Thus the README in the GitHub repo (for v0.2) does not apply for the newest version available from Container Registry (v0.1.1).

Even the simplest example is broken now, in v0.2.0 vs. v0.1.1.

So please do like Bicep / ARM documentation ( https://learn.microsoft.com/en-us/azure/templates/microsoft.web/serverfarms?pivots=deployment-language-bicep ): Publish versioned documentation tied to a resource module for easier lookup.

matebarabas commented 3 months ago

@Azure/avm-core-team-technical-bicep, can you please take a look at this request? Thanks!

AlexanderSehr commented 3 months ago

Hey @o-l-a-v, thanks for raising this. It's a known request since CARML for which I already proposed some possible solutions back in the day. However, the team was not able to agree on an approach so this did not (yet) go anywhere.

For the BRM repository the story is similar, yet not entirely the same. 'Technically' you can find all ReadMe's because each time a module is published, a release tag is created that contains the point in time reference of the module's readme. However, crawling manually through releases isn't a good experience either so I would not call this a 'solution'.

@matebarabas, I think we should put this on the agenda for the core team (especially Bicep). Not only is this a long running issue, but I wouldn't trust us using the releases as we do today forever anyways either. Thoughts?

cc: @eriqua

matebarabas commented 3 months ago

I think this can be achieved now relatively simply, by extending the version listing feature of the module index, @jtracey93 has recently implemented. By clicking on the version badges, a JSON view is opened with all the version of the module that were ever released. This could be updated to a view, where each version would be clickable, pointing to particular tagged version and the module's folder in the GH repo. This way, from the module indexes, one would easily access documentation of a given module version.