Clarify name prefix requirements for classes and enums
@michaeltlombardi is already working on this.
Since Apr 5, 2023.
Assessment
This issue has not been assessed yet.
Description
Prerequisites
- Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
- Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in
Get-Foocmdlet" instead of "Typo." - Verify Version: If there is a mismatch between documentation and the module on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.
Version
v2.0
Links
- https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/blob/9a81631df4048e98ed5788d6a10eeb9516d864ea/dsc/docs-conceptual/dsc-2.0/concepts/class-based-resources.md?plain=1#L258
- https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/blob/9a81631df4048e98ed5788d6a10eeb9516d864ea/dsc/docs-conceptual/dsc-2.0/concepts/class-based-resources.md?plain=1#L309
- https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/blob/9a81631df4048e98ed5788d6a10eeb9516d864ea/dsc/docs-conceptual/dsc-2.0/concepts/class-based-resources.md?plain=1#L365
- https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/blob/9a81631df4048e98ed5788d6a10eeb9516d864ea/dsc/docs-conceptual/dsc-2.0/concepts/class-based-resources.md?plain=1#L559-L566
- https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/blob/9a81631df4048e98ed5788d6a10eeb9516d864ea/dsc/docs-conceptual/dsc-2.0/concepts/class-based-resources.md?plain=1#L794
Summary
If a class or enum is defined with the same name in more than one module, compiling configurations that use both of those modules fails due to the name collision.
Details
We already partially cover this problem for defining the Reasons property for machine configuration:
We should generalize this note and advice and surface it wherever it makes sense.
Suggested Fix
We should document this behavior, suggest that authors prefix their enums and classes with their module name, and add name prefixing to the best practices section for the Class-based DSC Resources article.
We may want to add an include that we can use throughout the documentation wherever we're talking about naming classes and enums for use as DSC Resource property types.
- Dominant language
- PowerShell
- Stars
- 60
- Forks
- 48
- Avg merge
- 8h 35m
- Merged PRs (30d)
- 5
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from MicrosoftDocs/PowerShell-Docs-DSC
-
issue-doc-idea needs-triage
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
needs-triage
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
-
dsc-v3 issue-doc-idea
MicrosoftDocs/PowerShell-Docs-DSC#364 · 1 comment · 1 assignee ·
-
needs-triage
Difficulty 3/5 1-2 days Newbie friendliness 35/100
MicrosoftDocs/PowerShell-Docs-DSC#350 · 4 comments · 1 reaction ·
-
needs-triage
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
MicrosoftDocs/PowerShell-Docs-DSC#326 · 6 comments ·