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
364 stars 85 forks source link

[Documentation Update]: Module names - clarity #1621

Open jbinko opened 4 weeks ago

jbinko commented 4 weeks ago

Check for previous/existing GitHub issues

Description

The following sections describe the naming conventions for modules, but contributors are not required to create these names themselves. Instead, we should direct them to the csv link where they can find the pre-assigned module names. https://azure.github.io/Azure-Verified-Modules/specs/shared/#naming-convention https://azure.github.io/Azure-Verified-Modules/specs/shared/#bicep-resource-module-naming https://azure.github.io/Azure-Verified-Modules/specs/shared/#bicep-pattern-module-naming

I suggest adding notes in the links above with pointer to csv to recommend that contributors utilize existing module names.

You can find the existing names of modules here: https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/BicepResourceModules.csv

This approach prevents any confusion for new contributors attempting to devise module names based on complex naming conventions.

eriqua commented 4 weeks ago

Hi @jbinko, thanks for raising this issue.

Module names are not preassigned, but provided by contributors raising a module proposal. Only after that the module name will be listed in the csv file. Hence, contributors should be aware of the naming convention before the name is listed.

Could you please elaborate more on which part of the documentation is unclear in that sense? Exactly which phase of the contribution are we talking about (e.g., before the module proposal/after the proposal but before the first release/update of an existing module)?

Thanks!

jbinko commented 3 weeks ago

From my experience, while the owner may suggest a module name, it can be changed. The key information for beginning implementation is found in the CSV file. This file contains essential data assigned to you after the initial proposal. The idea is to simplify the process for contributors, allowing them to use the CSV file rather than having to fully comprehend all the details in the specification documents. This approach can be highly beneficial for contributors.

https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/BicepResourceModules.csv

IMO, we should emphasize and incorporate these points in the documentation - including the link.

eriqua commented 3 weeks ago

Thanks a lot @jbinko for elaborating. Would you see it useful then to add link and details about the csv to the contribution guide rather than the specs? Would you see this issue related to #1600?

jbinko commented 3 weeks ago

Yeah, including a link in the spec and more details about it could be beneficial. We aim to encourage the community to read the specs thoroughly. Adding more clarity and hints within the spec could improve understanding, in my opinion.

eriqua commented 3 weeks ago

Cc @matebarabas @ReneHezser