Skip to content

Latest commit

 

History

History
17 lines (13 loc) · 6.1 KB

HighQualityModuleGuidelines.md

File metadata and controls

17 lines (13 loc) · 6.1 KB
Raw

Creating a High Quality DSC Resource Module

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, in a few cases they can be overridden with permission from a DSC team member. PSSA errors are checked in the common tests.
Unit and Integration Tests are functional and follow the guidelines
  • There should be at least one unit and one integration test file for each resource (under Tests\Unit and Tests\Integration subdirectories respectively)
  • Test guidelines are being followed
  • Tests use test templates
  • Unit tests have at least 70% code coverage and do not depend on any outside modules or special environments to run - they should run out of the box and use mocks for any external function calls.
  • Tests are written using Pester test framework
  • Tests are integrated with appveyor
 Make sure unit tests test specific functionality of the resource and that as much of the code is tested as possible. Mock-out any external function calls. The minimum criteria will be checked by the common tests (>=70% coverage, no outside dependencies, unit and integration test files present)
Examples are complete and useful
  • There should be at least one example file for each resource
  • Examples clearly show how to use all of the exported functions of each of the resources in the module, they work correctly out of the box, are PSSA clean, and are clearly documented
 Go through each exported function and make sure there is an example that shows how to use it. 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 included in a sub folder of the module. Modules will be checked to ensure an Examples folder and at least one example file are present. 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 (should follow readme.md template 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.
 Each time the module is updated, the version must also be updated and include 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 schema.mof file.
  • The root folder contains a file: moduleName.psd1 with proper structure (defines ProjectUri, LicenseUri and Tags)
  • Correct license document present (MIT license recommended)
 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
  • Module should be named SomethingDsc e.g. SharePointDsc, we no longer use "x" in front of the module name. If module is not production ready, we indicate it by providing version less than 1.0, e.g. 0.1
  • If module had "x" prefix before and is now being updated to meet High Quality DSC Resource Module requirements, we should create a new branch (called xSomething, e.g. xSharePoint) which contains latest released code of "x" version of the module (in order to be able to provide critical fixes for those if necessary)
 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 Guidelines
  • 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