Permalink
Browse files

Updating repo guidelines (#317)

* Updating module submission guides

* Clarified naming schema - not all resources are either "X" or "hqrm"
* Removed guidelines for submitting new modules

* New mantainer rule

* Create naming document

* Update CONTRIBUTING.md

typo fix

* addressing feedback

* addressing feedback

* Beginning to flesh out the process

* Update CONTRIBUTING.md

* Update Naming.md

* introduce supportability page

* Refactor Naming as independent of Supportability

* minor grammar and url fixes

* Propose deprecating "x" based on community feedback

* typo

* Revision to proposal for supportability page

* tweaks to support references

* minor tweaks and improvement on HQRM tagging

* reduce explanation to be more crisp

* Remove “even”

Writing docs is equally important

* implement suggestions from reviewable

* fix contributing and naming based on feedback
  • Loading branch information...
zjalexander authored and kwirkykat committed Dec 6, 2017
1 parent 6fa283a commit 79aaeb77c6005a24a94c85862ccac5f2dd271ef2
Showing with 179 additions and 20 deletions.
  1. +9 −20 CONTRIBUTING.md
  2. +5 −0 Maintainers.md
  3. +113 −0 Naming.md
  4. +52 −0 Supportability.md
View
@@ -6,8 +6,6 @@ There are a few different ways you can contribute:
* [Submit an issue](#submitting-an-issue)
* [Fix an issue](#fixing-an-issue)
* [Submit a new resource](#submitting-a-new-resource)
* [Submit a new resource module (repository)](#submitting-a-new-resource-module)
* [Write documentation](#writing-documentation)
* [Review pull requests](#reviewing-pull-requests)
@@ -33,7 +31,7 @@ Here are the steps:
### Find the Correct Repository
| Issue Topic | Where to Submit |
|-------------|-----------------|
| <ul><li> DSC Resource Kit overall </li><li> Issues that span multiple resource modules </li><li> DSC Resource Kit processes </li><li> Resource module proposals </li><li> Resource module submissions </li><li> Resource proposals that don't fit in an existing module </li></ul> | DscResources (this repository!) |
| <ul><li> DSC Resource Kit overall </li><li> Issues that span multiple resource modules </li><li> DSC Resource Kit processes </li></ul> | DscResources (this repository!) |
| <ul><li> Common tests </li><li> Meta-fixers </li></ul> | [DscResource.Tests](https://github.com/PowerShell/DscResource.Tests)
| <ul><li> Bugs, feature requests, enhancements to a specific resource </li><li> Resource proposals </li></ul> | The repository of the resource module that contains/should contain the resource. |
| <ul><li> Bugs, feature requests, enhancements that span multiple resources within one resource module </li></ul> | The repository of that resource module |
@@ -363,24 +361,18 @@ All mof-based resource (with Get/Set/Test-TargetResource and a schema.mof file)
Composite resource (with a configuration and a .psd1 file) files must have the exact same name as the resource or they will not be able to be imported. Hence, composite resource files should not have the MSFT_ prefix (e.g. xResource.psm1).
If you are adding a new resource to an experimental/preview module (module name starts with 'x'), the resource name must also start with 'x' (e.g. MSFT_xResource.psm1 or xResource.psm1).
If you are adding a new resource to a high quality module (module name does not start with 'x' and ends with 'Dsc'), the resource name should not start with 'x' (e.g. MSFT_Resource.psm1 or Resource.psm1).
If you are adding a new resource to an unsupported module (module name starts with 'x'), the resource name must also start with 'x' (e.g. MSFT_xResource.psm1 or xResource.psm1).
If the module name does not start with 'x', the resource name should not start with 'x' (e.g. MSFT_Resource.psm1 or Resource.psm1).
For clarity, any test or example files for the resource should be named to match the files for the same resource. For example, if the main resource file is named 'MSFT_xResource.psm1', then the unit test file should be named 'MSFT_xResource.Tests.ps1'.
Any test or example files for the resource should be named to match the files for the same resource. For example, if the main resource file is named 'MSFT_xResource.psm1', then the unit test file should be named 'MSFT_xResource.Tests.ps1'. Consistent naming helps the review process.
## Submitting a New Resource Module
If you would like a new DSC resource module added to the DSC Resource Kit, please check the [existing issues](https://github.com/PowerShell/DscResources/issues) in this repository first to make sure no one else is already working on a similar module.
If someone is already working on a similar module, please leave a comment on the open issue or add a GitHub reaction to the top comment to **express your interest**. You can also offer help and use the issue to coordinate your efforts.
For more details, please see [Naming](Naming.md).
If none of the existing module proposals or submissions are related to one you want, open a new issue in [this repository](https://github.com/PowerShell/DscResources/issues) with the following information:
## Submitting a New Resource Module
This repository is **not** accepting new modules at this time. We recommend authoring the resource in your own repository and [submitting it to the gallery](https://docs.microsoft.com/en-us/powershell/gallery/psgallery/creating-and-publishing-an-item) under your own name. However, feel free to bring up any modules you have authored during the [DSC Resoucrce Kit Community Call](https://github.com/PowerShell/DscResources/tree/master/CommunityCalls).
* What system will your module be managing?
- For example, [xActiveDirectory](https://github.com/powershell/xActiveDirectory) models and manages Active Directory
* What resources you would like to be included in the new resource module?
* Will your module include [MOF-based resources](https://technet.microsoft.com/en-us/library/dn956964.aspx) (compatible with PS/WMF 4.0 and 5.0+) or [class-based resources](https://technet.microsoft.com/en-us/library/dn948461.aspx) (only compatible with PS/WMF 5.0+)
* Are you or will you be working on this module or would you like someone else to pick it up?
## Developing a new resource
Next, develop your new module in your own repository.
Make sure to:
* Follow the standard DSC Resource Kit module structure.
@@ -404,10 +396,7 @@ Make sure to:
* Use the template from the [DscResource.Template folder](DscResource.Template) as a boilerplate for [appveyor.yml] (https://github.com/PowerShell/DscResources/blob/master/DscResource.Template/appveyor.yml) (Continuous Integration configuration file) and [README.md](https://github.com/PowerShell/DscResources/blob/master/DscResource.Template/README.md).
* Run the common tests located in [DSCResource.Tests](https://github.com/PowerShell/DscResource.Tests) which will be automatically installed into the root folder of your module when your tests are run if your module is accepted in the DSC Resource Kit.
All new resource modules should follow the DSC Resource Kit [High Quality guidelines](HighQualityModuleGuidelines.md).
High quality resource modules may then use the ___Dsc naming format (e.g. SharePointDsc).
Once you are ready to submit your new module, follow the submission process [here](NewResourceModuleSubmissions.md).
All new resources in existing resource modules should should follow the [High Quality resource module guidelines](HighQualityModuleGuidelines.md).
## Writing Documentation
One of the easiest ways to contribute to a PowerShell project is to write and edit documentation.
View
@@ -19,6 +19,10 @@ Maintainers have the power to:
## Current Maintainers
Being a mantainer is a time-consuming task!
If you find you no longer have the time for this role, please let us know.
That helps us keep contributors up-to-date on what to expect for certain repositories.
If you should be on this list but are not, please tag [@kwirkykat](https://github.com/kwirkykat) in an issue or send [@katiedsc](https://twitter.com/katiedsc) a private message on Twitter.
All repositories without dedicated maintainers are maintained by the current DSC Resource Kit owners, Katie Keim ([@kwirkykat](https://github.com/kwirkykat)) and Mariah Breakey ([@mbreakey3](https://github.com/mbreakey3)).
@@ -89,6 +93,7 @@ All repositories without dedicated maintainers are maintained by the current DSC
If you are maintainer, please follow these rules:
1. **DO** take care of pull requests in a timely manner.
1. **DO** ensure that each contributor has signed a valid Contributor License Agreement (CLA).
1. **DO** reply to new issues and pull requests (after you finish reviewing and everything looks good to you, leave a comment like "Looks good to me" or "LGTM" so we know that someone has looked at it and approved it).
1. **DO** make sure contributors are following the [contributor guidelines](https://github.com/PowerShell/DscResources/blob/master/CONTRIBUTING.md).
View
113 Naming.md
@@ -0,0 +1,113 @@
# DSC Resource Naming
This document clarifies the naming convention for DSC Resource Modules.
- [Module Naming](##module-naming)
- ["Dsc" Suffix](##dsc-suffix)
- [High Quality Resource Module tag (HQRM)](##high-quality-resource-module)
*Previously documented conventions:*
- [(Deprecated) Expiremental (xResource)](##deprecated-expiremental)
- [(Deprecated) Community created (cResource)](##deprecated-community-created)
## 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](http://github.com/powershell/dscresources) repository
- Includes an expectation of
[project structure](CONTRIBUTING.md#developing-a-new-resource),
including [documentation](CONTRIBUTING.md#writing-documentation),
[tests](CONTRIBUTING.md#write-tests) and
[CI](CONTRIBUTING.md#tests-in-appveyor) process to revalidate
at every push to source
- 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](http://powershellgallery.com).
## 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](http://powershellgallery.com).
## High Quality Resource Module
The community reviews modules [submitted to the community call](CommunityAgenda.md)
in order to determine if they meet an agreed-upon level of quality.
These modules follow the
[high quality DSC resource guidelines](HighQualityModuleGuidelines.md).
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](Supportability.md).
Modules that meet HQRM requirements will be identified
in [DscResources](http://github.com/powershell/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](http://powershellgallery.com)
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](http://semver.org/).
## Support
The concepts of Naming and supportability are unrelated.
For details see the [supportability](Supportability.md) informational page.
View
@@ -0,0 +1,52 @@
# PowerShell DSC Community Support Guidance
This document discusses the approach to support for DSC configurations and resources
published by the community.
This is a community guidance document and not intended to be a legal/support document.
For information on support programs available from Microsoft Corporation,
see [the following website](https://support.microsoft.com/en-us/allproducts)
and the category specific to the product or service where you use PowerShell.
Support beyond what is described in this page
might be available with those additional services.
## Are DSC resources supported by Microsoft
Microsoft supports PowerShell and the PowerShell Desired State Configuration
engine, Local Configuration Manager (LCM).
## What should I expect if I call Microsoft for support on a DSC Resource
When a new support case is opened and the focus is on DSC,
the person assisting the customer will attempt to resolve the issue
and if needed will include engineering support such as the PowerShell team.
The PowerShell team would determine if there is an issue with PowerShell or with LCM.
If help is needed beyond those areas the case might lead to guiding the customer
to open a new issue in that community project (GitHub repo),
a recommendation to engage a 3rd party company/organization that published the DSC Resource,
or escalation with other teams at Microsoft.
With community supported artifacts,
the case would be closed once a new issue has been submitted to the project.
## Who provides support for the technologies managed by DSC
The maintainers for DSC resources should clearly identify in the project README
if additional support is available.
An example would be if a Microsoft product or service engineering team
has agreed to extend their support to include DSC resources,
or if a 3rd party software company/organization provides support for DSC resources.
A template for documenting this will be available for community maintainers.
If support is not documented for a project,
then it defaults to unsupported.
## How does this apply to the naming of a resources
The naming of DSC resources includes an identifier of quality
as explained in the [Naming](Naming.md) informational page,
that is governed by the community of active DSC Resource contributors.
The expression of quality for a DSC Resource is a distinct metric from supportability.
The concepts of DSC Resource naming and support
should be considered unrelated.

0 comments on commit 79aaeb7

Please sign in to comment.