Skip to content
This repository has been archived by the owner on Feb 24, 2021. It is now read-only.

Latest commit

 

History

History
114 lines (85 loc) · 4.72 KB

Naming.md

File metadata and controls

114 lines (85 loc) · 4.72 KB

DSC Resource Naming

This document clarifies the naming convention for DSC Resource Modules.

Previously documented conventions:

Quality Governance

The community of Open Source contributors holds each other, and Microsoft, accountable to quality through a process that includes:

  • Code review prior to listing in DSC Resource repository
  • Contributor community monthly Skype call
  • Established baseline of "High Quality" to set goals for contributors seeking best practice guidance

The PowerShell team is a stakeholder in the community. Anyone contributing to or even consuming these projects can participate in improving the DSC Resources available by providing feedback, filing issues, authoring new tests, or assisting with documentation.

Module Naming

When possible, a DSC resource can be combined with PowerShell functions in a single module. The module scope should be a "scenario" such as a single product or solution, and both export commands for general use and DSC resources to declaratively manage the same components.

If no module exists within the scope of the scenario, there is no need to append a special identifier in the name. The module should include the metadata tag "DSCResource" to clearly identify it in the PowerShell Gallery.

Dsc Suffix

When creating a module for DSC resources that will be paired with an existing PowerShell module, the best approach is to combine the original module name with the suffix "Dsc". This clearly identifies intent to align with the existing module.

Even with the "Dsc" suffix, the module should include the metadata tag "DSCResource" to clearly identify it in the PowerShell Gallery.

High Quality Resource Module

The community reviews modules submitted to the community call in order to determine if they meet an agreed-upon level of quality. These modules follow the high quality DSC resource guidelines.

HQRM should be viewed as adherence to best practices and can be included as a tag throughout the entire life of development as long as the guidelines are followed. It is not an "end state", and is unrelated to supportability.

Modules that meet HQRM requirements will be identified in DscResources repository when the community has agreed that the project is adhering to requirements.

(Deprecated) Experimental

When DSC was originally introduced, it was communicated that new modules should be prefixed with an "x" to help identify that the work might not be suitable for use in a production environment.

The community has now matured and guidelines exist to hold project maintainers accountable through the use of CI process where tests are required and the results are publicly available. Anyone that would like to evaluate the quality of a module can view the project documentation, code, tests, and test results, to understand if the work is suitable for their environment.

The "x" prefix is no longer required. Resources that include the prefix are free to deprecate the convention going forward.

The existing work will remain available in the PowerShell Gallery so there is no risk to existing Configurations. For Configurations that use modules that include an "x", see the project sites for communication from the maintainers about when a name change could occur.

(Deprecated) Community Created

Similar to the "x" prefix, at the launch of DSC there was communication that people contributing their own DSC resources prefix it with "c". This was because the resource modules were distributed via TechNet. Since we have moved to GitHub, this requirement is no longer valid.

Versioning

In addition to naming, contributors should express incremental changes through proper versioning from release to release. The recommended versioning strategy for DSC projects is semantic versioning.

Support

The concepts of Naming and supportability are unrelated. For details see the supportability informational page.