CONTRIBUTING.md

Contribution guidance

work in progress

All PnP repositories are following up on the standard PnP process on getting started and contribute.

See following PnP wiki page from the main repository for additional details.

• For getting started guidance, see Setting up your environment.

*Notice that you'll need to update the URLs based on used repository. All community contributions are also more than welcome. Please see following page for additional insights on the model.

• For contributing to PnP, see Contributing to Office 365 developer patterns and practices

---

Code contributions

In order to succesfully compile the PnP PowerShell solution you will also have to download and build in Visual Studio the PnP-Sites-Core repository and make the dev branch available. The PowerShell solution depends on it. In order to succesfully compile it, make sure that PnP-Sites-Core is located at the same level as PnP-PowerShell.

So:

c:\[YOUR REPO FOLDER]\PnP-Sites-Core
c:\[YOUR REPO FOLDER]\PnP-PowerShell

The reason for this is that the PnP-PowerShell library will have references to the release and debug builds of the PnP-Sites-Core library.

A few notes:

Every new cmdlet should provide help and examples

As documentation is autogenerated by building the solution, make sure that you include both help and examples, alike

 [Cmdlet("Get", "SPOStoredCredential")]
 [CmdletHelp("Returns a stored credential from the Windows Credential Manager", Category = "Base Cmdlets")]
 [CmdletExample(Code = "PS:> Get-SPOnlineStoredCredential -Name O365", 
                Remarks = "Returns the credential associated with the specified identifier",
                SortOrder = 1)]
  public class GetStoredCredential : PSCmdlet
  {
  }

Most cmdlets will extend SPOWebCmdlet which provides a few helper objects for you to use, like SelectedWeb and ClientContext

As most cmdlets are 'web sensitive' (e.g. you can specify a -Web parameter to point to a different subweb), make sure that you use the correct ClientContext. When a user specifies the -Web parameter in a cmdlet that extens SPOWebCmdlet, the cmdlet will switch it's internal context to that web, reusing credentials. It is important to use the right context, and the easiest way to do that is to use

var context = SelectedWeb.Context;

Cmdlets will have to work both on-premises and in the cloud

You can use preprocessor variables ("ONPREMISES" or "SP2013" and "SP2016") to build different cmdlets for the different targets. In cases where it is not possible to provide functionality for either the cloud or on-premises, make sure to remove the full cmdlet from the compiled solution by having #IF(!SP2013) or #IF(SP2013) as the _first line of the cmdlet, before using statements.

See the following example

#if !ONPREMISES
using Microsoft.SharePoint.Client;

public class MyCmdlet : SPOWebCmdlet
{
   // cmdlet code omitted
}
#endif

If only parts of a cmdlet require different behaviour based upon the different version of the SDK, you are recommended to use the #ONPREMISES or other available preprocessor variable throughout your code to exclude or include certain code.

Cmdlets will have to use common verbs

The verb of a cmdlet (get-, add-, etc.) should follow acceptable cmdlet standards and should be part of one of the built in verbs classes (VerbsCommon, VerbsData, etc.):

Documentation contributions

If you want to contribute to cmdlet documentation, please do not make a pull request to modify the actual files in the Documentation folder itself. Those files are automatically generated based upon comments in the actual classes. So if you want to modify documentation and or add an example of a cmdlet, navigate to the corresponding class where the cmdlet is being implemented and add the comments there. An example can for instance be found in

https://github.com/OfficeDev/PnP-PowerShell/blob/dev/Commands/Fields/AddField.cs

Notice the [CmdletHelp("")] and [CmdletExample()] class attributes that describe the cmdlet.