Enable resource modules to opt-in to publish example configurations to PowerShell Gallery

[johlju]

Love some feedback on this, if there are any thoughts, suggestions or problems around this.

The proposal is to allow the test framework to publish the examples in the AppVeyor deploy step, but only if it is a ‘master’ branch build ($env:APPVEYOR_REPO_BRANCH -eq 'master').

It should deploy all scripts that passes Test-ScriptFileInfo. That way the contributors can control which examples, under the ‘Examples’ folder, are published . By adding script file information to an example, a resource module automatically opt-in to publish that example to the PowerShell Gallery (if already activated in the appveyor.yml).

I suggest adding this as a new cmdlet in the appveyor.yml deply script step (Invoke-AppVeyorDeployTask). This is so that same functionality can be used for both the "default shared"-model and the "harness"-model, and also so that it is possible to manually run the deploy step if need be.
For the Publish-Script to work each repo that opt-in must have the API Key as a secure environment variable in appveyor.yml - for DSC Resource Kit resource modules, this should be the same account (at least what I'm thinking now).

Published examples must have the same configuration name as the file name to be able to deploy in Azure Automation. Today the test framework looks for a configuration named Example in the example script file and tries to compile the example, that need to be changed in the test framework to be able to validate examples that should be published to PowerShell Gallery. Simplest is to try calling both Example (as today) and the same name as the filename, since examples published to the PowerShell Gallery must have the same file name as the configuration name.

These are the requirements/dependencies for publishing to PowerShell Gallery (updated if new requirements/dependencies are found).

• Publish only on 'master' build.
• Must have opt-in for common test "example validation".
• Publish only example that passes Test-ScriptFileInfo.
• Publish only example that does not already exist (for example has a newer version).
• Example file name and configuration name must end with 'Config'.
• Example filename and configuration name must be the same.
• Rename example files that begin with '1-', '-2' ('^[0-9]+-') before publish (so they still work with auto-documentation).
• (Optional) New common tests that check so there are no duplicate GUID's in the repository (prevent copy/paste mistakes).
• The name can contain only letters, numbers, and underscores. The name must start with a letter, and it must end with a letter or a number.

Done by contributors:

• Make sure the example filename is descriptive, and ends with 'Config'.
  • If the example is for a single resource, then preferably prefix resource name in descriptive filename and configuration name.
• Make sure Node is targeting 'localhost' (or equivalent) .
• Make sure the filename and configuration name match.
• Add script metadata to example.
• Make sure example have an unique GUID.
• Make sure example have comment-based help.
• Version and release notes in each examples metadata must be updated by the contributor on change.

Example of script metadata, #Requires statement and comment-based help:

<#PSScriptInfo
.VERSION 1.0.4
.GUID 124cf79c-d637-4e50-8199-5cf4efb3572d
.AUTHOR Microsoft Corporation
.COMPANYNAME Microsoft Corporation
.COPYRIGHT
.TAGS DSCConfiguration
.LICENSEURI https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/master/LICENSE
.PROJECTURI https://github.com/PowerShell/xPSDesiredStateConfiguration
.ICONURI
.EXTERNALMODULEDEPENDENCIES xPSDesiredStateConfiguration
.REQUIREDSCRIPTS
.EXTERNALSCRIPTDEPENDENCIES
.RELEASENOTES First version.
.PRIVATEDATA 2016-Datacenter,2016-Datacenter-Server-Core
#>

#Requires -module @{ModuleName = 'xPSDesiredStateConfiguration';ModuleVersion = '8.2.0.0'}

<#
    .SYNOPSIS
        Creates a file at the given file path with the specified content through
        the xScript resource.

    .DESCRIPTION
        Creates a file at the given file path with the specified content through
        the xScript resource.

    .PARAMETER FilePath
        The path at which to create the file. Defaults to $env:TEMP.

    .PARAMETER FileContent
        The content to set for the new file.
        Defaults to 'Just some sample text to write to the file'.
#>

[johlju]

In PowerShellGallery Publishing Guidelines and Best Practices it says

We recommend you subscribe to Comments for each PowerShell Gallery item you publish. This allows you to be notified if anyone comments on your items in the PowerShell Gallery. This is optional, as it requires creating an account with LiveFyre.

I'm not sure we can do that unless there are some API or webhook that we can subscribe through.