All High Quality DSC Resource Modules must pass these guidelines and checks before a Pull Request is accepted. xWebAdministration is currently one of the main modules that we are trying to get to meet these guidelines.
| Criterion | Details | Developer Story | Validation |
|---|---|---|---|
| PS Script Analyzer is clean | All mandatory rules pass and flagged rules pass or have been overridden for resources and examples. For now, warnings/information level violations are okay in tests, but there must be no error-level violations anywhere. | If there are any rules that aren't passing they will show up as an error when the common tests are run. Any messages that show up as warning/flagged must be fixed if possible, in a few cases they can be overridden with permission from a DSC team member. | PSSA errors are checked in the common tests. |
| Unit Tests are functional | Unit tests have at least 70% code coverage and they have no outside dependencies | Make sure unit tests test specific functionality of the resource and that as much of the code is tested as possible. | The minimum criteria will be checked by the common tests (>=70% coverage & no outside dependencies) |
| Examples are complete and useful | Examples clearly show how to use the different features of the module, they work correctly out of the box, are PSSA clean, and are clearly documented | Go through each function and make sure there is an example that shows how to use each feature of the module. There should be examples that don't have any outside dependencies so users can easily run them as well as real-world examples that more extensively show the functionality of the module. Any example that has outside dependencies must be put in a sub folder. Specific checks will be done when the common tests are run. | Modules will be checked for having an Examples folder and at least one example file. The examples will be checked for PSSA errors and the simple examples will be checked to make sure there are no outside dependencies. |
| Module is well-documented and free of commented out code and TODOs | There is a README.md file which gives an overview of the module - what it does, how to use it, requirements for the environment needed to run the module, etc. Code is also sufficiently commented so that it is easy to follow what's going on | There will be a link provided for a template for the README.md file as well as an example file. In addition, every time the module is updated, the version also needs to be updated with comments on the changes. | There will be a check that a README.md file exists, but the clarity, completeness, and cleanliness of this document will need to be manually reviewed. |
| The module follows a set uniform folder and file format | In the root folder there is a 'Tests' Folder with both a 'Unit' and an 'Integration' subfolder. In the root folder there is an 'Examples' folder with at least one simple example file as well as an optional subfolder with any example files that contain outside dependencies. In the root folder there is a 'DSCResources' folder that contains all the resources contained in their own folder. Within each resource folder there is a .psd1 file and a schema.mof file. The root folder contains a file: moduleName.psd1 | Ensure this format is followed | There will be a test to check to make sure the module follows this folder format |
| Module does not require git to use | If the module uses git anywhere, there must be an alternative for the user so that the module can be used on a machine with/without git | Ensure that git is not necessary anywhere in the code | There will be a test for this - if git commands are used anywhere then they will be flagged for review - in some instances it is okay as long as it's not necessary to run the module |
| There is no 'x' in front of the module name | The new naming format is still under discussion but there will be no 'x' and there will be some general prefix/postfix labeling it as a DSC resource. PascalCase will be the standard format | Name the module as per the final naming guidelines | The general format of the name will be checked as one of the common tests |
| The module follows DSC Resource Kit Style Guidlines | These are the guidelines created and updated by the DSC team - make sure code follows them | Follow these guidelines | The rules that can be easily tested will be in the common tests or added as PSSA rules, others will need to be manually checked |