feat: Added diverse specs for User-defined types #1738

AlexanderSehr · 2024-11-27T21:28:55Z

Description

New structure-aligned version of #1711

Added diverse specs for User-defined types:

BCPNFR9 - Category: Inputs - Decorators
BCPNFR18 - Category: User-defined types - Specification
BCPNFR19 - Category: User-defined types - Naming
BCPNFR20 - Category: User-defined types - Export
BCPNFR21 - Category: User-defined types - Decorators
BCPRMNFR2 - Category: User-defined types - AVM-Common-Types

…m/Azure/Azure-Verified-Modules

AlexanderSehr · 2024-11-28T20:26:10Z

Dependend on #1737

matebarabas · 2024-12-02T21:48:41Z

docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR1.md

@@ -20,7 +20,7 @@ tags: [
 priority: 11010
 ---

-#### ID: BCPNFR1 - Category: Inputs - Data Types
+#### ID: BCPNFR1 - Category: Inputs - User-defined types - General


@AlexanderSehr, I know this is not here to be reviewed yet, but I want to add an important comment: be aware that if you change this title, it will start breaking legacy links that are still pointing to the specs present on the old shared and Bicep/TF specific pages. This is unavoidable, and I'm not saying you shouldn't rename an article if the name is off, but you need to be aware of this side effect.

Hey @matebarabas,
thanks for the comment. 💪 The spec is actually absolutely here to be reviewed - but - is unfortunately dependent on this PR which is pending a review by @eriqua :)
In any case, you have a point - yet I'd argue the title should be changed to make more sense in the context of the other specs (which are about specific topics in the space of UDTs).
Also, sure this could break references (if they happen to exist), but personally I am strongly against prioritizing backward compatibility over usability/correctness. Just to explain the angle I'm coming from 😉

So... can this comment be resolved, @matebarabas?

Can any applicable link be updated via search and replace?

Can any applicable link be updated via search and replace?

No, as the ones I was referring to are auto-generated based on the title. I agree to Alex's comment on not prioritizing backward compatibility if we feel something is just simply off. Feel free to resolve this.

So... can this comment be resolved, @matebarabas?

Yes please, that's what I was hoping to express by sending a thumb-up on your comment. :) I knew I should've been more explicit. :)

AlexanderSehr · 2024-12-11T22:20:12Z

Ready to go @eriqua :)

eriqua · 2024-12-12T01:42:25Z

docs/content/specs-defs/includes/bicep/resource/non-functional/BCPRMNFR2.md

+tags: [
+  Class-Resource, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Type-NonFunctional, # SINGLE VALUE: this can be "Type-Functional" OR "Type-NonFunctional"
+  Category-Inputs/Outputs, # SINGLE VALUE: this can be "Category-Testing" OR "Category-Telemetry" OR "Category-Contribution/Support" OR "Category-Documentation" OR "Category-CodeStyle" OR "Category-Naming/Composition" OR "Category-Inputs/Outputs" OR "Category-Release/Publishing"  Language-Bicep, # MULTIPLE VALUES: this can be "Language-Bicep" AND/OR "Language-Terraform"


Language-bicep tag looks commented out, please check

eriqua · 2024-12-12T01:45:35Z

docs/content/specs-defs/includes/bicep/resource/non-functional/BCPRMNFR2.md

+  Persona-Owner, # MULTIPLE VALUES: this can be "Persona-Owner" AND/OR "Persona-Contributor"
+  Persona-Contributor, # MULTIPLE VALUES: this can be "Persona-Owner" AND/OR "Persona-Contributor"
+  Lifecycle-BAU, # SINGLE VALUE: this can be "Lifecycle-Initial" OR "Lifecycle-BAU" OR "Lifecycle-EOL"
+  Validation-TBD # SINGLE VALUE: this can be "Validation-Manual" OR "Validation-CI/Informational" OR "CI/Enforced"


Can we use the right value for new specs? AFAIK the intention going forward is to assign the tacmg based on the current static validation situation, and update it every time we update static validation in BRM.
E.g., currently it should be Validation-Manual, since we don't have a static test. Once we add it, it should be updated to Validation-CI/Informational (if soft failure) or Enforced (if required)

Suggested change

Validation-TBD # SINGLE VALUE: this can be "Validation-Manual" OR "Validation-CI/Informational" OR "CI/Enforced"

Validation-Manual # SINGLE VALUE: this can be "Validation-Manual" OR "Validation-CI/Informational" OR "CI/Enforced"

This applies to all specs below

eriqua · 2024-12-12T01:48:58Z

docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR1.md

@@ -1,5 +1,5 @@
 ---
-title: BCPNFR1 - Data Types
+title: BCPNFR1 - User-defined types - General


I think this one should temporarily be a SHOULD and not a MUST

eriqua · 2024-12-12T01:50:00Z

docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR18.md

+param subnets subnetsType
+type subnetsType = { ... }[]?
+```
+the type should instead be defined like


Suggested change

the type should instead be defined like

the type should be defined like

eriqua · 2024-12-12T02:00:07Z

docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR21.md

+
+#### ID: BCPNFR21 - Category: User-defined types - Decorators
+
+Similar to [BCPNFR9](#id-bcpnfr9---category-inputs---decorators), User-defined types MUST implement certain [decorators](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameters#use-decorators), while they SHOULD others.


Not very clear. I'd suggest to divide into 2 paragraphs, covering the MUST and the SHOULD part

eriqua · 2024-12-12T02:00:53Z

docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR9.md

+
+#### ID: BCPNFR9 - Category: Inputs - Decorators
+
+Input parameters MUST make use of certain [decorators](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameters#use-decorators), while they SHOULD make use of others whenever possible.


Same comment of the related for UDT

eriqua · 2024-12-12T02:01:35Z

docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR21.md

+Decorators that SHOULD be implemented include but are not limited to `allowed`, `minValue`, `maxValue`, `minLength` & `maxLength` as they have a big impact on the module's usability.
+
+```bicep
+@desciption('My type''s description.')


Suggested change

@desciption('My type''s description.')

@description('My type''s description.')

eriqua · 2024-12-12T02:11:43Z

docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR18.md

+  Class-Resource, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Class-Pattern, # MULTIPLE VALUES: this can be "Class-Resource" AND/OR "Class-Pattern" AND/OR "Class-Utility"
+  Type-NonFunctional, # SINGLE VALUE: this can be "Type-Functional" OR "Type-NonFunctional"
+  Category-Inputs/Outputs, # SINGLE VALUE: this can be "Category-Testing" OR "Category-Telemetry" OR "Category-Contribution/Support" OR "Category-Documentation" OR "Category-CodeStyle" OR "Category-Naming/Composition" OR "Category-Inputs/Outputs" OR "Category-Release/Publishing"


I'm getting confused between the title and this label. Should we add a label Category-UserDefinedTypes? Or are all falling into the Inputs/Outputs label?

@eriqua, this is used to control under which section of the specs page in question (e.g. bicep res page) the given spec will show up. Introducing anything new would require the shortcode and the page structure to be updated, so I strongly recommend trying to categorize what we need under one of the existing categories. These could work imho:

inputs/outputs

naming/composition (because of the latter)

codestyle

Then I'm not sure of how useful categories are and I'm afraid we're locking ourselves into a process we ourselves enforced. Don't get me wrong but we are saying that adding a new label would be too complex and we prefer to enforce a different, not ideal one instead to overcome that complexity.
The fact that 3 different categories may apply for a single-valued label makes me wonder if we shouldn't rethink the category static approach. Looking forward to brainstorming that

I think I tried to write it in a way that at least one of the specs shows up on two pages by adding both tags. I think that worked :D If I'm not mistaken I did that because it was for inputs & naming

AlexanderSehr added 3 commits November 27, 2024 22:02

Updated docs

027d408

Merge branches 'users/alsehr/cmkSpec' and 'main' of https://github.co…

34b0ae7

…m/Azure/Azure-Verified-Modules

Updated docs

cf72496

AlexanderSehr requested a review from a team as a code owner November 27, 2024 21:28

microsoft-github-policy-service bot added the Needs: Triage 🔍 Maintainers need to triage still label Nov 27, 2024

AlexanderSehr self-assigned this Nov 27, 2024

AlexanderSehr added Type: Documentation 📄 Improvements or additions to documentation and removed Needs: Triage 🔍 Maintainers need to triage still labels Nov 27, 2024

AlexanderSehr marked this pull request as draft November 28, 2024 20:25

AlexanderSehr requested a review from eriqua November 28, 2024 20:26

matebarabas reviewed Dec 2, 2024

View reviewed changes

AlexanderSehr added 3 commits December 11, 2024 23:16

Update to latest

46da669

Update to latest

0cae562

Update to latest

5048e15

AlexanderSehr marked this pull request as ready for review December 11, 2024 22:19

AlexanderSehr enabled auto-merge (squash) December 11, 2024 22:19

eriqua reviewed Dec 12, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Added diverse specs for User-defined types #1738

feat: Added diverse specs for User-defined types #1738

AlexanderSehr commented Nov 27, 2024 •

edited

Loading

AlexanderSehr commented Nov 28, 2024

matebarabas Dec 2, 2024 •

edited

Loading

AlexanderSehr Dec 2, 2024 •

edited

Loading

AlexanderSehr Dec 11, 2024

eriqua Dec 12, 2024

matebarabas Dec 12, 2024

AlexanderSehr commented Dec 11, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

eriqua Dec 12, 2024

matebarabas Dec 12, 2024

eriqua Dec 12, 2024 •

edited

Loading

AlexanderSehr Dec 12, 2024 •

edited

Loading

	Validation-TBD # SINGLE VALUE: this can be "Validation-Manual" OR "Validation-CI/Informational" OR "CI/Enforced"
	Validation-Manual # SINGLE VALUE: this can be "Validation-Manual" OR "Validation-CI/Informational" OR "CI/Enforced"

	the type should instead be defined like
	the type should be defined like


		#### ID: BCPNFR21 - Category: User-defined types - Decorators

		Similar to [BCPNFR9](#id-bcpnfr9---category-inputs---decorators), User-defined types MUST implement certain [decorators](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameters#use-decorators), while they SHOULD others.


		#### ID: BCPNFR9 - Category: Inputs - Decorators

		Input parameters MUST make use of certain [decorators](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameters#use-decorators), while they SHOULD make use of others whenever possible.

	@desciption('My type''s description.')
	@description('My type''s description.')

feat: Added diverse specs for User-defined types #1738

Are you sure you want to change the base?

feat: Added diverse specs for User-defined types #1738

Conversation

AlexanderSehr commented Nov 27, 2024 • edited Loading

Description

AlexanderSehr commented Nov 28, 2024

matebarabas Dec 2, 2024 • edited Loading

Choose a reason for hiding this comment

AlexanderSehr Dec 2, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlexanderSehr commented Dec 11, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eriqua Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

AlexanderSehr Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

AlexanderSehr commented Nov 27, 2024 •

edited

Loading

matebarabas Dec 2, 2024 •

edited

Loading

AlexanderSehr Dec 2, 2024 •

edited

Loading

eriqua Dec 12, 2024 •

edited

Loading

AlexanderSehr Dec 12, 2024 •

edited

Loading