Contributing to SharePointDsc
If you are keen to make SharePointDsc better, why not consider contributing your work to the project? Every little change helps us make a better resource for everyone to use, and we would love to have contributions from the community.
We follow all of the standard contribution guidelines for DSC resources outlined in DscResources repo, so please review these as a baseline for contributing. Specifically be sure to read the following linked articles from that page:
To help ensure that SharePointDsc resources are created in a consistent manner, there are a number of design guidelines that guide the thinking applied to how the resources should be built. These design rules should be taken into account when submitting changes or new functionality to the SharePointDsc module.
- Each resource in SharePointDsc should strive to make changes to only the current server, and not require a remote connection to other servers to complete their work.
- Supported versions of SharePoint for SharePointDsc are SharePoint Server 2013 with Service Pack 1 or higher, SharePoint Server 2016 and SharePoint Server 2019. SharePoint 2010 will not be supported due to requiring PowerShell 4, which is not supported with that version of the product. Where a resource will not work with all versions we support (such as functionality or features being added or deprecated between versions), a clear and concise error should be returned that explains this.
- Any breaking change should be committed to a new branch so that it can be included in the next major version release. A change will be considered a 'breaking' change under the following circumstances:
- A new mandatory property is added to a resource
- The data type of any resource property is changed
- Any property is removed or renamed in a resource
- A resource is removed
- A change in the expected outcome of how a resource behaves is made
- Any change that modifies the prerequisites to use SharePointDsc is made
With over 70 resources in our module, we want to keep the documentation work light. To aid this, we are generating our documentation dynamically. Therefore, for each DSC resource we have, the following items must be completed so we can generate these.
- In the folder for the resource, place a readme.md file that contains heading 'Description' and a text description of the module.
- In the schema.mof file for the resource, ensure that there are description attributes on all properties.
- Generate 1 or more example configurations for the resource in the Examples/resources/[resource name] folder using PowerShell help syntax to describe the example at the top of the file. Each example configuration must be complete and runnable, must be called "example" and it must only take parameters of PSCredential types. This will allow our unit tests to validate the examples as part of our build process.
With these items in place, we can dynamically generate the help files for PowerShell as well as this wiki.
SharePointDsc is designed to work correctly against the Server 2013, 2016 and 2019 versions of the product. The automated unit tests that are run in SharePointDsc will execute against both versions of the product using the stub modules we include in the unit tests directory.
Where a resource applies to only a specific version (such as xSPUserProfileSyncService) the code should throw meaningful errors to indicate that it should not be used with the installed version of the product.
