Merge branch 'master' into issue-#96-gitrefs-implement

Author: HowardWolosky

.github/PULL_REQUEST_TEMPLATE.md

@@ -32,10 +32,10 @@
 -->
 - [ ] You actually ran the code that you just wrote, especially if you did just "one last quick change".
 - [ ] Comment-based help added/updated, including examples.
-- [ ] [Static analysis](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#static-analysis)
-is reporting back clean.
+- [ ] [Static analysis](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#static-analysis) is reporting back clean.
 - [ ] New/changed code adheres to our [coding guidelines](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#coding-guidelines).
+- [ ] New/changed code continues to [support the pipeline](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#pipeline-support).
 - [ ] Changes to the manifest file follow the [manifest guidance](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#module-manifest).
-- [ ] Unit tests were added/updated and are all passing. See [testing guidelines](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#testing).
+- [ ] Unit tests were added/updated and are all passing. See [testing guidelines](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#testing).  This includes making sure that all pipeline input variations have been covered.
 - [ ] Relevant usage examples have been added/updated in [USAGE.md](https://github.com/microsoft/PowerShellForGitHub/blob/master/USAGE.md).
 - [ ] If desired, ensure your name is added to our [Contributors list](https://github.com/microsoft/PowerShellForGitHub/blob/master/CONTRIBUTING.md#contributors)

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            // Run this launch config and then set breakpoints in your module.
+            // Then you can `Import-Module -Force ./PowerShellForGitHub.psd1`
+            // and run a function that will hit the breakpoint.
+            "name": "PowerShell: Interactive Session",
+            "type": "PowerShell",
+            "request": "launch",
+            "cwd": ""
+        }
+    ]
+}

.vscode/settings.json

@@ -1,4 +1,7 @@
 {
+    "editor.rulers": [
+        100
+    ],
     "[powershell]": {
         "files.trimTrailingWhitespace": true
     },

CONTRIBUTING.md

@@ -23,6 +23,7 @@ Looking for information on how to use this module?  Head on over to [README.md](
 *   [Adding New Configuration Properties](#adding-new-configuration-properties)
 *   [Code Comments](#code-comments)
 *   [Debugging Tips](#debugging-tips)
+*   [Pipeline Support](#pipeline-support)
 *   [Testing](#testing)
     *   [Installing Pester](#installing-pester)
     *   [Configuring Your Environment](#configuring-your-environment)
@@ -152,7 +153,7 @@ Update-Module -Name PSScriptAnalyzer
 Once it's installed (or updated), from the root of your enlistment simply call
 
 ```powershell
-Invoke-ScriptAnalyzer -Path .\ -Recurse
+Invoke-ScriptAnalyzer -Settings ./PSScriptAnalyzerSettings.psd1 -Path ./ -Recurse
 ```
 
 That should return with no output.  If you see any output when calling that command,
@@ -242,7 +243,8 @@ Here are some general guidelines
   reviewing/maintaining code.  There are of course exceptions, but this is generally an enforced
   preference.  The [Visual Studio Productivity Power Tools](https://visualstudiogallery.msdn.microsoft.com/34ebc6a2-2777-421d-8914-e29c1dfa7f5d)
   extension has a "Column Guides" feature that makes it easy to add a Guideline in column 100
-  to make it really obvious when coding.
+  to make it really obvious when coding.  If you use VS Code, this module's `.vscode/settings.json`
+  configures that for you automatically.
 
 ----------
 
@@ -286,8 +288,71 @@ Set-GitHubConfiguration -LogRequestBody
 
 ----------
 
+### Pipeline Support
+
+This module has comprehensive support for the PowerShell pipeline.  It is imperative that all
+new functionality added to the module embraces this design.
+
+ * Most functions are declared as a `filter`.  This is the equivalent of a `function` where the
+   body of the function is the `process` block, and the `begin/end` blocks are empty.
+
+ * In limited cases where one of the inputs is an array of something, and you specifically want that
+   to be processed as a single command (like adding a bunch of labels to a single issue at once),
+   you can implement it as a `function` where you use `begin/process` to gather all of the values
+   into a single internal array, and then do the actual command execution in the `end` block.  A
+   good example of that which you can follow can be seen with `Add-GitHubIssueLabel`.
+
+ * Any function that requires the repo's `Uri` to be provided should be additionally aliased with
+   `[Alias('RepositoryUrl')]` and its `[Parameter()]` definition should include `ValueFromPipelineByPropertyName`.
+
+ * Do not use any generic term like `Name` in your parameters.  That will end up causing unintended
+   pipeline issues down the line.  For instance, if it's a label, call it `Label`, even though `Name`
+   would make sense, other objects in the pipeline (like a `GitHub.Respository` object) also have
+   a `name` property that would conflict.
+
+ * You should plan on adding additional properties to all objects being returned from an API call.
+   Any object that is specific to a repository should have a `RepositoryUrl` `NoteProperty` added
+   to it, enabling it to be piped-in to any other command that requires knowing which repository
+   you're talking about.  Additionally, any other property that might be necessary to uniquely
+   identify that object in a different command should get added properties.  For example, with Issues,
+   we add both an `IssueNumber` property and an `IssueId` property to it, as the Issue commands
+   need to interact with the `IssueNumber` while the Event commands interact with the `IssueId`.
+   We prefer to _only_ add additional properties that are believed to be needed as input to other
+   commands (as opposed to creating alias properties for all of the object's properties).
+
+ * For every major file, you will find an `Add-GitHub*AdditionalProperties` filter method at the end.
+   If you're writing a new file, you'll need to create this yourself (and model it after an existing
+   one).  The goal of this is that you can simply pipe the output of your `Invoke-GHRestMethod`
+   directly into this method to update the result with the additional properties, and then return
+   that modified version to the user.  The benefit of this approach is that you can then apply that
+   filter on child objects within the primary object.  For instance, a `GitHub.Issue` has multiple
+   `GitHub.User` objects, `GitHub.Label` objects, a `GitHub.Milestone` object and more.  Within
+   `Add-GitHubIssueAdditionalProperties`, it just needs to know to call the appropriate
+   `Add-GitHub*AdditionalProperties` method on the qualifying child properties, without needing to
+   know anything more about them.
+
+ * That method will also "type" information to each object.  This is forward-looking work to ease
+   support for providing formatting of various object types in the future.  That type should be
+   defined at the top of the current file at the script level (see other files for an example),
+   and you should be sure to both specify it in the `.OUTPUTS` section of the Comment Based Help (CBH)
+   for the command, as well as with `[OutputType({$script:GitHubUserTypeName})]` (for example).
+
+ * Going along with the `.OUTPUTS` is the `.INPUTS` section.  Please maintain this section as well.
+   If you add any new type that will gain a `RepositoryUrl` property, then you'll need to update
+   virtually _all_ of the `.INPUTS` entries across all of the files where the function has a `Uri`
+   parameter.  Please keep these type names alphabetical.
+
+ * To enable debugging issues involving pipeline support, there is an additional configuration
+   property that you might use:  `Set-GitHubConfiguration -DisablePipelineSupport`.  That will
+   prevent the module from adding _any_ additional properties to the objects.
+
+----------
+
 ### Testing
 [![Build status](https://dev.azure.com/ms/PowerShellForGitHub/_apis/build/status/PowerShellForGitHub-CI?branchName=master)](https://dev.azure.com/ms/PowerShellForGitHub/_build/latest?definitionId=109&branchName=master)
+[![Azure DevOps tests](https://img.shields.io/azure-devops/tests/ms/PowerShellForGitHub/109/master)](https://dev.azure.com/ms/PowerShellForGitHub/_build/latest?definitionId=109&branchName=master)
+[![Azure DevOps coverage](https://img.shields.io/azure-devops/coverage/ms/PowerShellForGitHub/109/master)](https://dev.azure.com/ms/PowerShellForGitHub/_build/latest?definitionId=109&branchName=master)
+
 
 #### Installing Pester
 This module supports testing using the [Pester UT framework](https://github.com/pester/Pester).
@@ -350,6 +415,8 @@ There are many more nuances to code-coverage, see
 
 #### Automated Tests
 [![Build status](https://dev.azure.com/ms/PowerShellForGitHub/_apis/build/status/PowerShellForGitHub-CI?branchName=master)](https://dev.azure.com/ms/PowerShellForGitHub/_build/latest?definitionId=109&branchName=master)
+[![Azure DevOps tests](https://img.shields.io/azure-devops/tests/ms/PowerShellForGitHub/109/master)](https://dev.azure.com/ms/PowerShellForGitHub/_build/latest?definitionId=109&branchName=master)
+[![Azure DevOps coverage](https://img.shields.io/azure-devops/coverage/ms/PowerShellForGitHub/109/master)](https://dev.azure.com/ms/PowerShellForGitHub/_build/latest?definitionId=109&branchName=master)
 
 These test are configured to automatically execute upon any update to the `master` branch
 of `microsoft/PowerShellForGitHub`.
@@ -362,9 +429,9 @@ as well...it is stored, encrypted, within Azure DevOps.  It is not accessible fo
 the CI pipeline.  To run the tests locally with your own account, see
 [configuring-your-environment](#configuring-your-environment).
 
-> NOTE: We're currently encountering issues with the tests successfully running within the pipeline.
-> They do complete successfully locally, so please test your changes locally before submitting a
-> pull request.
+> Your change must successfully pass all tests before they will be merged.  While we will run a CI
+> build on your behalf for any submitted pull request, it's to your benefit to verify your changes
+> locally first.
 
 #### New Test Guidelines
 Your tests should have NO dependencies on an account being set up in a specific way.  They should
@@ -486,6 +553,7 @@ Thank you to all of our contributors, no matter how big or small the contributio
 - **[Shannon Deminick (@Shazwazza)](http://github.com/Shazwazza)**
 - **[Jess Pomfret (@jpomfret)](https://github.com/jpomfret)**
 - **[Giuseppe Campanelli (@themilanfan)](https://github.com/themilanfan)**
+- **[Christoph Bergmeister (@bergmeister)](https://github.com/bergmeister)**
 
 ----------
 

GitHubAnalytics.ps1

@@ -24,8 +24,12 @@ function Group-GitHubIssue
         The date property that should be inspected when determining which week grouping the issue
         if part of.
 
+    .INPUTS
+        GitHub.Issue
+
     .OUTPUTS
-        [PSCustomObject[]] Collection of issues and counts, by week, along with the total count of issues.
+        [PSCustomObject[]]
+        Collection of issues and counts, by week, along with the total count of issues.
 
     .EXAMPLE
         $issues = @()
@@ -90,8 +94,12 @@ function Group-GitHubIssue
             foreach ($week in $weekDates)
             {
                 $filteredIssues = @($Issue | Where-Object {
-                    (($DateType -eq 'Created') -and ($_.created_at -ge $week) -and ($_.created_at -le $endOfWeek)) -or
-                    (($DateType -eq 'Closed') -and ($_.closed_at -ge $week) -and ($_.closed_at -le $endOfWeek))
+                    (($DateType -eq 'Created') -and
+                     ($_.created_at -ge $week) -and
+                     ($_.created_at -le $endOfWeek)) -or
+                    (($DateType -eq 'Closed') -and
+                     ($_.closed_at -ge $week) -and
+                     ($_.closed_at -le $endOfWeek))
                 })
 
                 $endOfWeek = $week
@@ -144,6 +152,9 @@ function Group-GitHubPullRequest
         The date property that should be inspected when determining which week grouping the
         pull request if part of.
 
+    .INPUTS
+        GitHub.PullRequest
+
     .OUTPUTS
         [PSCustomObject[]] Collection of pull requests and counts, by week, along with the
         total count of pull requests.
@@ -211,8 +222,12 @@ function Group-GitHubPullRequest
             foreach ($week in $weekDates)
             {
                 $filteredPullRequests = @($PullRequest | Where-Object {
-                    (($DateType -eq 'Created') -and ($_.created_at -ge $week) -and ($_.created_at -le $endOfWeek)) -or
-                    (($DateType -eq 'Merged') -and ($_.merged_at -ge $week) -and ($_.merged_at -le $endOfWeek))
+                    (($DateType -eq 'Created') -and
+                     ($_.created_at -ge $week) -and
+                     ($_.created_at -le $endOfWeek)) -or
+                    (($DateType -eq 'Merged') -and
+                     ($_.merged_at -ge $week) -and
+                     ($_.merged_at -le $endOfWeek))
                 })
 
                 $endOfWeek = $week
@@ -265,6 +280,7 @@ function Get-WeekDate
         Get-WeekDate -Weeks 10
 #>
     [CmdletBinding()]
+    [OutputType([DateTime[]])]
     param(
         [ValidateRange(0, 10000)]
         [int] $Weeks = 12