feat: Added diverse specs for User-defined types #1738
Conversation
microsoft-github-policy-service
bot
added
the
Needs: Triage 🔍
AlexanderSehr
added
Type: Documentation 📄
|
Dependend on #1737 |
|
Ready to go @eriqua :) |
| 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" |
There was a problem hiding this comment.
Language-bicep tag looks commented out, please check
There was a problem hiding this comment.
This is by design as it is part of the comment. Hence also all the other key-words
There was a problem hiding this comment.
In the comment it says 'Single value' and the one that was chosen was Category-Input/Outputs
docs/content/specs-defs/includes/bicep/resource/non-functional/BCPRMNFR2.md
Outdated
Show resolved
Hide resolved
| @@ -1,5 +1,5 @@ | |||
| --- | |||
| title: BCPNFR1 - Data Types | |||
| title: BCPNFR1 - User-defined types - General | |||
There was a problem hiding this comment.
I think this one should temporarily be a SHOULD and not a MUST
There was a problem hiding this comment.
Do we have temporary specs? :D I phrased it in the way I did with the perspective of 'how it should be' or what we know what 1.0 will be. I understand why you want to SHOULD, but I guess I wasn't aware we're writing specs in this way (but instead don't enforce them all before 1.0)
docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR18.md
Outdated
Show resolved
Hide resolved
|
|
||
| #### 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. |
There was a problem hiding this comment.
Not very clear. I'd suggest to divide into 2 paragraphs, covering the MUST and the SHOULD part
There was a problem hiding this comment.
Updated. Please let me know what you think :)
|
|
||
| #### 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. |
There was a problem hiding this comment.
Same comment of the related for UDT
There was a problem hiding this comment.
Also updated. Please let me know what you think :)
docs/content/specs-defs/includes/bicep/shared/non-functional/BCPNFR21.md
Outdated
Show resolved
Hide resolved
| 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" |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
@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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
Would be nice if that's the way it worked. Then a spec could show up in every list it makes sense in.
…CPNFR21.md Co-authored-by: Erika Gressi <[email protected]>
…CPNFR18.md Co-authored-by: Erika Gressi <[email protected]>
…/BCPRMNFR2.md Co-authored-by: Erika Gressi <[email protected]>
|
Linked to Azure/bicep-registry-modules#4098 |
Description
New structure-aligned version of #1711
Added diverse specs for User-defined types: