diff --git a/overview.md b/overview.md new file mode 100644 index 0000000..a04e184 --- /dev/null +++ b/overview.md @@ -0,0 +1,59 @@ +# Overview + +This Visual Studio Team Services extension adds build and release tasks for common project types. These tasks also support the pipelines generated by [Yo Team](https://github.com/DarqueWarrior/generator-team). + +## Categories + +### PowerShell Module Development + +#### Tasks + +##### Update Build Number + +Sets the VSTS build number to match the PowerShell Module version and the VSTS Build ID. This ensures that that build number matches the version of the package published, which helps in traceability. + +##### Install PowerShell Module + +Installs a PowerShell module with PowerShellGet. [PowerShellGet is included with PowerShell 5 or newer and is available for PowerShell 3 and 4 via an MSI](https://docs.microsoft.com/en-us/powershell/gallery/psget/get_psget_module?WT.mc_id=-vsts-stmuraws) + +Modules will be installed to the `CurrentUser` scope of the user account that the build agent is running under. The other option would be to install to the `AllUsers` scope, which requires administrator rights on the machine. + +Inputs: + +* `Scope` : `CurrentUser` or `AllUsers`. The default is `CurrentUser`. + +##### Run Static Code Analysis (PSScriptAnalyzer) + +Installs [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) if it is missing. + +Uses PSScriptAnalyzer to evaluate the quality of PowerShell script in your project. + +If you project has a `PSScriptAnalyzerSettings.psd1` file in the root of your project, those settings will be respected. + +By default, the build will only fail on `Error` results from PSScriptAnalyzer. The severity can be set to `Warning` or `Information` to perform more rigorous validations. + +Inputs: + +* `Severity` : `Information`, `Warning`, or `Error`. The default is `Error`. + +##### Run Unit Tests (Pester) + +Installs Pester if it is missing. + +Runs all the Pester tests defined under `./unit` (or otherwise specified file or directory). If a directory is specified, tests will be discovered recursively from any `*.Tests.ps1` file. Test results and code coverage reporting will be uploaded to VSTS for the build summary. + +Tags can be used to filter which tests are run or skipped. Tags should be specified in a space separated string. (Example: Setting `IncludeTags` to `RunMe RunMeToo AndMe` would run the tests three tags and no others.) + +Inputs: + +* `TestDirectory`: `./unit`. +* `IncludeTags` : Space separated strings. Default is an empty string (no tags). +* `ExcludeTags` : Space separated strings. Default is an empty string(no tags). + +##### Package Module + +Creates a PowerShell package that can be uploaded to a Nuget server or PowerShell Gallery. Any dependent modules are also created/saved locally for upload unless `ExcludeDependentModules` is set to `true`. + +Inputs: + +* `ExcludeDependentModules` : `true` or `false`. Default value is `false`. diff --git a/vss-extension.json b/vss-extension.json index 066e5b8..ca47bbb 100644 --- a/vss-extension.json +++ b/vss-extension.json @@ -21,7 +21,7 @@ ], "content": { "details": { - "path": "README.md" + "path": "overview.md" }, "license": { "path": "LICENSE"