DSC Resource Naming Guidelines
-
When DSC was announced at TechEd 2013, one of the goals was to “Create an ecosystem”.
The ecosystem for DSC has grown tremendously in the last 4 years.
At worldwide events for PowerShell (PowerShell + DevOps Global Summit, PowerShell Conference EU, PowerShell Conference Asia) there have been presentations lead by people actively using DSC to discuss real world, success, challenges, and community projects to resolve common issues. In addition there are community projects to build solutions for DSC entirely driven by the community, such as Datum to manage configuration data at scale, BaselineManagement to convert Group Policy to DSC configurations, and ReverseDSC to replicate known environments.
The PowerShell Gallery includes 1100 DSC Resources across 254 unique modules. Of those 1100 DSC Resources, 411 are currently released by the DSC team from the DSC Resource Kit.
During events and the monthly DSC Resource Kit community calls over the past year, I have heard consistently that the naming convention for DSC Resources is ready for an update. Most notably, the experimental “x” prefix and HQRM guidance could be confusing and does not match the approach used in other similar community ecosystems.
The Old Naming Convention
The original recommendation was to name resources using the following prefixes:
- “x” to identify a resource that is experimental and not supported
- “c” to identify a community modification
Resources that met a community agreed upon quality bar, or “High Quality Resource Modules”, have been using a naming suffix “Dsc”.
The New Naming Convention
The community has discussed and agreed upon a new simplified standard, explained in a recent update to the documentation.
DSC Resources going forward are no longer required to use the “x” or “c” naming conventions.
Instead, the guideline is that resources should use either the existing module name (if DSC Resources are combined with an existing module containing PowerShell functions) or the “Dsc” suffix. The best practices for finding a DSC Resource module is to search the PowerShell Gallery using the “DSC Resource” filter, or use the cmdlet:
<pre>Find-DscResource</pre>
The project name will not have any relationship with how or whether the project is supported. The documentation merged today also addresses this topic.
Why is it the right time to make this change
This is only possible because the DSC community, especially the DSC Resource project maintainers, are so passionate and actively working with DSC users to make the ecosystem better for everyone. The maintainers hold each other accountable to quality and technically enforce this through test automation.
The first community contributions to the DSC Resource Kit contained only the PowerShell code for the DSC module. The expectation for a contribution today includes following best practices, style guidelines, documentation, and test automation to demonstrate quality. As an example, the SharePointDsc module includes 2102 tests that must pass to accept a new contribution, and anyone can review the results of a new build. Similarly, SQLServerDsc includes 2507 tests (and has already adopted the new naming standard), xWebAdministration has 1032, and xActiveDirectory includes 653.
How do I know if a DSC Resource is supported
The old naming convention using “x” and “c” prefixes required users to modify their code when switching from experimental to stable versions of a module. Support for DSC Resources should come from the organization supporting the technology that is being managed. The best way to make that clear is to express it in the project Readme. Just as someone interested in consuming the resource should review the project code and make sure it is suitable for their environment, they should review the entire project documentation.
When will this change happen
Finally, this change does not need to be implemented “overnight”. As maintainers release future versions of their projects and determine they are ready, they can choose to retire the “x” convention. The PowerShell Gallery will provide access to future releases by the new name and the history of previous releases by the old name. The project repository will be the source of truth.
Thank you!
Michael Greene @migreene
Principal Program Manager
PowerShell DSC, Azure Automation DSC, and Azure Management Communityhttps://blogs.msdn.microsoft.com/powershell/2017/12/08/dsc-resource-naming-and-support-guidelines/
© Lightnetics 2024