├── .gitmodules ├── LICENSE ├── SampleConfig.ps1 ├── README.md └── CONTRIBUTING.md /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "TemplateConfig"] 2 | path = templateconfig 3 | url = http://github.com/powershell/templateconfig 4 | [submodule "dscconfiguration.tests"] 5 | path = dscconfiguration.tests 6 | url = http://github.com/powershell/dscconfiguration.tests 7 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2016 PowerShell Team 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /SampleConfig.ps1: -------------------------------------------------------------------------------- 1 | 2 | <#PSScriptInfo 3 | 4 | .VERSION 1.0.0.0 5 | 6 | .GUID 08b1d249-5522-40f8-94b4-37e46a6555b3 7 | 8 | .AUTHOR Michael Greene 9 | 10 | .COMPANYNAME Microsoft 11 | 12 | .COPYRIGHT 13 | 14 | .TAGS DSC Config 15 | 16 | .LICENSEURI https://github.com/PowerShell/DscConfigurations/blob/master/LICENSE 17 | 18 | .PROJECTURI https://github.com/PowerShell/DscConfigurations/ 19 | 20 | .ICONURI 21 | 22 | .EXTERNALMODULEDEPENDENCIES 23 | 24 | .REQUIREDSCRIPTS 25 | 26 | .EXTERNALSCRIPTDEPENDENCIES 27 | 28 | .RELEASENOTES 29 | 30 | 31 | #> 32 | 33 | <# 34 | 35 | .DESCRIPTION 36 | This is a simple example of a script that contains a PowerShell DSC Configuration but does not include any additional assets such as tests or documentation. 37 | 38 | #> 39 | 40 | Configuration SampleConfig { 41 | 42 | Registry WUServer { 43 | Key = 'HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\WindowsUpdate' 44 | ValueName = 'WUServer' 45 | ValueData = 'http://mywsusserver.mydomain.local' 46 | ValueType = 'String' 47 | Ensure = 'Present' 48 | } 49 | 50 | Registry WUStatusServer { 51 | Key = 'HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\WindowsUpdate' 52 | ValueName = 'WUStatusServer' 53 | ValueData = 'http://mywsusserver.mydomain.local' 54 | Ensure = 'Present' 55 | } 56 | 57 | } 58 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # DSC Configurations 2 | 3 | [![Join the chat at https://gitter.im/PowerShell/DscResources](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/PowerShell/DscResources?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 4 | 5 | Windows PowerShell Desired State Configuration (DSC) provides a configuration platform that is based on open standards. 6 | This repo provides a structured listing of **DSC Configurations** and guidance for Open Source community contribution. 7 | For information about the scripts that perform work described by Configurations, see the GitHub repo for [DSC Resources](http://github.com/powershell/dscresources). 8 | 9 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 10 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 11 | 12 | # Sharing Configurations 13 | ## Publishing a config to the Gallery should be done in one of these ways: 14 | 15 | ### Configuration Script 16 | If the Config is a script, create and require in the Script a separate module that contains the docs, help, examples, & tests. 17 | This ensures when the script is published or downloaded using PSGet cmdlets, the module will be brought along. 18 | 19 | You **must** use the RequiredModule metadata to specify the linked module. 20 | 21 | If there is a separate Config Data (PSD1) file, it belongs in the module. You **must** document how it is used. 22 | 23 | You **should** include a line generating the MOF in the script. 24 | 25 | You **may** include the Start-DscConfiguration command in the script. This means the script will be complete, but the deployment will start on script execution when it may or may not be appropriate in the user’s environment. 26 | 27 | ### Composite Resource 28 | If the Config is a Composite Resource, publish as a module that contains all the other items. 29 | You **should** consider publishing a script that uses the composite resource as in the preceeding option. 30 | 31 | ## Sharing relies on completing important metadata 32 | ```New-ModuleManifest``` and ```New-ScriptFileInfo``` will generate the placeholders for the metadata needed. 33 | 34 | All items published to the Gallery **must** have the correct metadata filled in for: 35 | - Author 36 | - Description 37 | - Version 38 | - Company name 39 | - Copyright. 40 | 41 | You **should** consider associating DSC resources with your configuration by using RequiredModule statements. 42 | This is a general best practice, as it allows users to make a single call to the gallery to geet all preqrequisites for running the script. However, there may be situations where it is incorrect. 43 | 44 | If you are using the DSCConfiguration.Tests repo to automate hosting tests on Azure VM's, you **should** also populate the a new property in PSPrivateData named "WindowsOSVersion" and set the value to one of the strings supported by AzureRM. 45 | 46 | # Authoring guidelines 47 | 48 | The [DSC Resource repository](http://github.com/powershell/dscresources) includes guidance on authoring that is applicable to configurations as well. 49 | For more information, visit the links below: 50 | 51 | - [Best practices](https://github.com/PowerShell/DscResources/blob/master/BestPractices.md) 52 | - [Style guidelines](https://github.com/PowerShell/DscResources/blob/master/StyleGuidelines.md) 53 | - [Maintainers](https://github.com/PowerShell/DscResources/blob/master/Maintainers.md) 54 | 55 | 56 | # Community Discussion 57 | 58 | There is a monthly community call hosted on Skype where new submissions and technical topics are discussed. 59 | For more information visit the topic [Community Agenda](https://github.com/PowerShell/DscResources/blob/master/CommunityAgenda.md). 60 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Requirements 2 | 3 | Configuration modules should meet a minimum baseline including integration tests and documentation. 4 | 5 | Additional information on contributing to the DSC Configurations repository can be found in the following DSC Resource topics: 6 | 7 | - [How to submit a new module](https://github.com/PowerShell/DscResources/blob/master/NewResourceModuleSubmissions.md) 8 | - [Getting started with GitHub](https://github.com/PowerShell/DscResources/blob/master/GettingStartedWithGitHub.md) 9 | - [Getting started with Pester](https://github.com/PowerShell/DscResources/blob/master/GettingStartedWithPester.md) 10 | 11 | ## Integration Tests 12 | 13 | DSC Configurations that are owned by the PowerShell Team and published to the gallery must be tested to verify functionality. 14 | Every change should results in the build service running a set of quality **Integration** tests. 15 | The integration tests verify that the AppVeyor service can successfully deploy the solution and run Get, Set, and Test without error. 16 | 17 | ## Acceptance Tests 18 | 19 | If possible, Configuration modules can also include **Acceptance** tests that verify the functionality of the solution after it is deployed. 20 | An example of an acceptance test would be loading a web page and verifying the content. 21 | 22 | ## Documentation 23 | 24 | Solutions provided by Configuration modules should include a ReadMe file with more information. 25 | At minimum, this includes: 26 | - A description of the current scope for the module. 27 | - List of the configurations included in the module. 28 | - Overview and requirements for each configuration. 29 | - Release notes that identify what changes across each version in the module release history. 30 | 31 | 32 | | Criterion | Details | Developer Story | Validation | 33 | |-----------|---------|-----------------|------------| 34 | | [PS Script Analyzer](https://github.com/PowerShell/PSScriptAnalyzer) is clean | | 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. | 35 | | Integration and Acceptance Tests are functional and follow the guidelines | | The configuration is proven to deliver a working configuration that delivers the intended functionality, and the solution can be replicated easily by anyone else. | All configurations will be checked by the common Get/Set/Test tests (100% coverage, no outside dependencies) | 36 | | Configuration is well-documented and free of commented out code and TODOs | | 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. | 37 | | The module follows a set uniform folder and file format | | Ensure this format is followed | There will be a test to check to make sure the module follows this folder format | 38 | | Module does not require git to use | | 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 | 39 | --------------------------------------------------------------------------------