Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
@ {
GitHubIssueTypeName = 'GitHub.Issue'
} . GetEnumerator ( ) | ForEach-Object {
Set-Variable -Scope Script -Option ReadOnly -Name $_ . Key -Value $_ . Value
}
filter Get-GitHubIssue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
<#
. SYNOPSIS
Retrieve Issues from GitHub .
. DESCRIPTION
Retrieve Issues from GitHub .
The Git repo for this module can be found here : http : / / aka . ms / PowerShellForGitHub
. PARAMETER OwnerName
Owner of the repository .
If not supplied here , the DefaultOwnerName configuration property value will be used .
. PARAMETER RepositoryName
Name of the repository .
If not supplied here , the DefaultRepositoryName configuration property value will be used .
. PARAMETER Uri
Uri for the repository .
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
them individually .
. PARAMETER OrganizationName
The organization whose issues should be retrieved .
. PARAMETER RepositoryType
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
all : Retrieve issues across owned , member and org repositories
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
ownedAndMember : Retrieve issues across owned and member repositories
. PARAMETER Issue
2020-05-08 01:04:51 +03:00
The number of specific Issue to retrieve . If not supplied , will return back all
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Issues for this Repository that match the specified criteria .
. PARAMETER IgnorePullRequests
GitHub treats Pull Requests as Issues . Specify this switch to skip over any
Issue that is actually a Pull Request .
. PARAMETER Filter
Indicates the type of Issues to return :
assigned : Issues assigned to the authenticated user .
created : Issues created by the authenticated user .
mentioned : Issues mentioning the authenticated user .
subscribed : Issues the authenticated user has been subscribed to updates for .
all : All issues the authenticated user can see , regardless of participation or creation .
. PARAMETER State
Indicates the state of the issues to return .
. PARAMETER Label
The label ( or labels ) that returned Issues should have .
. PARAMETER Sort
The property to sort the returned Issues by .
. PARAMETER Direction
The direction of the sort .
. PARAMETER Since
If specified , returns only issues updated at or after this time .
. PARAMETER MilestoneType
If specified , indicates what milestone Issues must be a part of to be returned :
specific : Only issues with the milestone specified via the Milestone parameter will be returned .
all : All milestones will be returned .
none : Only issues without milestones will be returned .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. PARAMETER MilestoneNumber
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Only issues with this milestone will be returned .
. PARAMETER AssigneeType
If specified , indicates who Issues must be assigned to in order to be returned :
specific : Only issues assigned to the user specified by the Assignee parameter will be returned .
all : Issues assigned to any user will be returned .
none : Only issues without an assigned user will be returned .
. PARAMETER Assignee
Only issues assigned to this user will be returned .
. PARAMETER Creator
Only issues created by this specified user will be returned .
. PARAMETER Mentioned
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Only issues that mention this specified user will be returned .
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2019-01-16 22:18:24 +03:00
. PARAMETER MediaType
The format in which the API will return the body of the issue .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Raw - Return the raw markdown body .
Response will include body .
This is the default if you do not pass any specific media type .
Text - Return a text only representation of the markdown body .
Response will include body_text .
Html - Return HTML rendered from the body ' s markdown .
Response will include body_html .
Full - Return raw , text and HTML representations .
Response will include body , body_text , and body_html .
2019-01-16 22:18:24 +03:00
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. PARAMETER AccessToken
If provided , this will be used as the AccessToken for authentication with the
REST Api . Otherwise , will attempt to use the configured value or will run unauthenticated .
. PARAMETER NoStatus
If this switch is specified , long-running commands will run on the main thread
with no commandline status update . When not specified , those commands run in
the background , enabling the command prompt to provide status information .
If not supplied here , the DefaultNoStatus configuration property value will be used .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. INPUTS
GitHub . Branch
GitHub . Content
GitHub . Event
GitHub . Issue
GitHub . IssueComment
GitHub . Label
GitHub . Milestone
GitHub . PullRequest
GitHub . Project
GitHub . ProjectCard
GitHub . ProjectColumn
GitHub . Release
GitHub . Repository
GitHub . User
. OUTPUTS
GitHub . Issue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. EXAMPLE
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Get-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -State Open
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Gets all the currently open issues in the microsoft \ PowerShellForGitHub repository .
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. EXAMPLE
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Get-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -State All -Assignee Octocat
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Gets every issue in the microsoft \ PowerShellForGitHub repository that is assigned to Octocat .
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
#>
[ CmdletBinding (
SupportsShouldProcess ,
2020-05-08 01:04:51 +03:00
DefaultParameterSetName = 'Elements' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ OutputType ( { $script:GitHubIssueTypeName } ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSShouldProcess " , " " , Justification = " Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently. " ) ]
param (
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $OwnerName ,
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $RepositoryName ,
[ Parameter (
Mandatory ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
ValueFromPipelineByPropertyName ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
ParameterSetName = 'Uri' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Alias ( 'RepositoryUrl' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Uri ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter ( ValueFromPipelineByPropertyName ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $OrganizationName ,
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'All' , 'OwnedAndMember' ) ]
[ string ] $RepositoryType = 'All' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter ( ValueFromPipelineByPropertyName ) ]
[ Alias ( 'IssueNumber' ) ]
2019-03-15 14:17:02 +03:00
[ int64 ] $Issue ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ switch ] $IgnorePullRequests ,
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'Assigned' , 'Created' , 'Mentioned' , 'Subscribed' , 'All' ) ]
[ string ] $Filter = 'Assigned' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'Open' , 'Closed' , 'All' ) ]
[ string ] $State = 'Open' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string[] ] $Label ,
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'Created' , 'Updated' , 'Comments' ) ]
[ string ] $Sort = 'Created' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'Ascending' , 'Descending' ) ]
[ string ] $Direction = 'Descending' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ DateTime ] $Since ,
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'Specific' , 'All' , 'None' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $MilestoneType ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter ( ValueFromPipelineByPropertyName ) ]
[ int64 ] $MilestoneNumber ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'Specific' , 'All' , 'None' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $AssigneeType ,
[ string ] $Assignee ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter ( ValueFromPipelineByPropertyName ) ]
[ Alias ( 'UserName' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Creator ,
[ string ] $Mentioned ,
2019-01-16 22:18:24 +03:00
[ ValidateSet ( 'Raw' , 'Text' , 'Html' , 'Full' ) ]
[ string ] $MediaType = 'Raw' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $AccessToken ,
[ switch ] $NoStatus
)
2018-11-20 00:07:05 +03:00
Write-InvocationLog
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2018-11-20 00:07:05 +03:00
$elements = Resolve-RepositoryElements -DisableValidation
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$OwnerName = $elements . ownerName
$RepositoryName = $elements . repositoryName
$telemetryProperties = @ {
'OwnerName' = ( Get-PiiSafeString -PlainText $OwnerName )
'RepositoryName' = ( Get-PiiSafeString -PlainText $RepositoryName )
'ProvidedIssue' = $PSBoundParameters . ContainsKey ( 'Issue' )
}
$uriFragment = [ String ] :: Empty
$description = [ String ] :: Empty
if ( $OwnerName -xor $RepositoryName )
{
$message = 'You must specify BOTH Owner Name and Repository Name when one is provided.'
Write-Log -Message $message -Level Error
throw $message
}
if ( -not [ String ] :: IsNullOrEmpty ( $RepositoryName ) )
{
$uriFragment = " /repos/ $OwnerName / $RepositoryName /issues "
$description = " Getting issues for $RepositoryName "
2018-12-14 01:31:37 +03:00
if ( $PSBoundParameters . ContainsKey ( 'Issue' ) )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
$uriFragment = $uriFragment + " / $Issue "
$description = " Getting issue $Issue for $RepositoryName "
}
}
elseif ( -not [ String ] :: IsNullOrEmpty ( $OrganizationName ) )
{
$uriFragment = " /orgs/ $OrganizationName /issues "
$description = " Getting issues for $OrganizationName "
}
2019-01-03 22:11:14 +03:00
elseif ( $RepositoryType -eq 'All' )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
$uriFragment = " /issues "
$description = " Getting issues across owned, member and org repositories "
}
2019-01-03 22:11:14 +03:00
elseif ( $RepositoryType -eq 'OwnedAndMember' )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
$uriFragment = " /user/issues "
$description = " Getting issues across owned and member repositories "
}
else
{
throw " Parameter set not supported. "
}
2019-01-03 22:11:14 +03:00
$directionConverter = @ {
'Ascending' = 'asc'
'Descending' = 'desc'
}
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$getParams = @ (
2019-01-03 22:11:14 +03:00
" filter= $( $Filter . ToLower ( ) ) " ,
" state= $( $State . ToLower ( ) ) " ,
" sort= $( $Sort . ToLower ( ) ) " ,
" direction= $( $directionConverter [ $Direction ] ) "
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
)
if ( $PSBoundParameters . ContainsKey ( 'Label' ) )
{
$getParams + = " labels= $( $Label -join ',' ) "
}
if ( $PSBoundParameters . ContainsKey ( 'Since' ) )
{
$getParams + = " since= $( $Since . ToUniversalTime ( ) . ToString ( 'o' ) ) "
}
if ( $PSBoundParameters . ContainsKey ( 'Mentioned' ) )
{
$getParams + = " mentioned= $Mentioned "
}
if ( $PSBoundParameters . ContainsKey ( 'MilestoneType' ) )
{
2019-01-03 22:11:14 +03:00
if ( $MilestoneType -eq 'All' )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
$getParams + = 'mentioned=*'
}
2019-01-03 22:11:14 +03:00
elseif ( $MilestoneType -eq 'None' )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
$getParams + = 'mentioned=none'
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
elseif ( $PSBoundParameters . ContainsKey ( '$MilestoneNumber' ) )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$message = " MilestoneType was set to [ $MilestoneType ], but no value for MilestoneNumber was provided. "
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Write-Log -Message $message -Level Error
throw $message
}
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
if ( $PSBoundParameters . ContainsKey ( 'MilestoneNumber' ) )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$getParams + = " milestone= $MilestoneNumber "
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
if ( $PSBoundParameters . ContainsKey ( 'AssigneeType' ) )
{
if ( $AssigneeType -eq 'all' )
{
$getParams + = 'assignee=*'
}
elseif ( $AssigneeType -eq 'none' )
{
$getParams + = 'assignee=none'
}
elseif ( [ String ] :: IsNullOrEmpty ( $Assignee ) )
{
$message = " AssigneeType was set to [ $AssigneeType ], but no value for Assignee was provided. "
Write-Log -Message $message -Level Error
throw $message
}
}
if ( $PSBoundParameters . ContainsKey ( 'Assignee' ) )
{
$getParams + = " assignee= $Assignee "
}
if ( $PSBoundParameters . ContainsKey ( 'Creator' ) )
{
$getParams + = " creator= $Creator "
}
if ( $PSBoundParameters . ContainsKey ( 'Mentioned' ) )
{
$getParams + = " mentioned= $Mentioned "
}
$params = @ {
'UriFragment' = $uriFragment + '?' + ( $getParams -join '&' )
'Description' = $description
2020-04-03 21:13:53 +03:00
'AcceptHeader' = ( Get-MediaAcceptHeader -MediaType $MediaType -AsJson -AcceptHeader $symmetraAcceptHeader )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'AccessToken' = $AccessToken
'TelemetryEventName' = $MyInvocation . MyCommand . Name
'TelemetryProperties' = $telemetryProperties
2018-11-20 00:07:05 +03:00
'NoStatus' = ( Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
2020-06-01 23:56:03 +03:00
try
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$result = ( Invoke-GHRestMethodMultipleResult @params | Add-GitHubIssueAdditionalProperties )
2020-06-01 23:56:03 +03:00
if ( $IgnorePullRequests )
{
return ( $result | Where-Object { $null -eq ( Get-Member -InputObject $_ -Name pull_request ) } )
}
else
{
return $result
}
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
2020-06-01 23:56:03 +03:00
finally { }
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
filter Get-GitHubIssueTimeline
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
<#
. SYNOPSIS
Retrieves various events that occur around an issue or pull request on GitHub .
. DESCRIPTION
Retrieves various events that occur around an issue or pull request on GitHub .
The Git repo for this module can be found here : http : / / aka . ms / PowerShellForGitHub
. PARAMETER OwnerName
Owner of the repository .
If not supplied here , the DefaultOwnerName configuration property value will be used .
. PARAMETER RepositoryName
Name of the repository .
If not supplied here , the DefaultRepositoryName configuration property value will be used .
. PARAMETER Uri
Uri for the repository .
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
them individually .
. PARAMETER Issue
The Issue to get the timeline for .
. PARAMETER AccessToken
If provided , this will be used as the AccessToken for authentication with the
REST Api . Otherwise , will attempt to use the configured value or will run unauthenticated .
. PARAMETER NoStatus
If this switch is specified , long-running commands will run on the main thread
with no commandline status update . When not specified , those commands run in
the background , enabling the command prompt to provide status information .
If not supplied here , the DefaultNoStatus configuration property value will be used .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. INPUTS
GitHub . Branch
GitHub . Content
GitHub . Event
GitHub . Issue
GitHub . IssueComment
GitHub . Label
GitHub . Milestone
GitHub . PullRequest
GitHub . Project
GitHub . ProjectCard
GitHub . ProjectColumn
GitHub . Release
GitHub . Repository
. OUTPUTS
GitHub . Event
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. EXAMPLE
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Get-GitHubIssueTimeline -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 24
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
#>
[ CmdletBinding (
SupportsShouldProcess ,
2020-05-08 01:04:51 +03:00
DefaultParameterSetName = 'Elements' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ OutputType ( { $script:GitHubEventTypeName } ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSShouldProcess " , " " , Justification = " Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently. " ) ]
2020-05-26 18:01:17 +03:00
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSReviewUnusedParameter " , " " , Justification = " One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1. " ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
param (
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $OwnerName ,
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $RepositoryName ,
[ Parameter (
Mandatory ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
ValueFromPipelineByPropertyName ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
ParameterSetName = 'Uri' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Alias ( 'RepositoryUrl' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Uri ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter (
Mandatory ,
ValueFromPipelineByPropertyName ) ]
[ Alias ( 'IssueNumber' ) ]
2019-03-15 14:17:02 +03:00
[ int64 ] $Issue ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $AccessToken ,
[ switch ] $NoStatus
)
2018-11-20 00:07:05 +03:00
Write-InvocationLog
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2018-11-20 00:07:05 +03:00
$elements = Resolve-RepositoryElements
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$OwnerName = $elements . ownerName
$RepositoryName = $elements . repositoryName
$telemetryProperties = @ {
'OwnerName' = ( Get-PiiSafeString -PlainText $OwnerName )
'RepositoryName' = ( Get-PiiSafeString -PlainText $RepositoryName )
}
$params = @ {
'UriFragment' = " repos/ $OwnerName / $RepositoryName /issues/ $Issue /timeline "
'Description' = " Getting timeline for Issue # $Issue in $RepositoryName "
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
'AcceptHeader' = $script:mockingbirdAcceptHeader
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'AccessToken' = $AccessToken
'TelemetryEventName' = $MyInvocation . MyCommand . Name
'TelemetryProperties' = $telemetryProperties
2018-11-20 00:07:05 +03:00
'NoStatus' = ( Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
return ( Invoke-GHRestMethodMultipleResult @params | Add-GitHubEventAdditionalProperties )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
filter New-GitHubIssue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
<#
. SYNOPSIS
Create a new Issue on GitHub .
. DESCRIPTION
Create a new Issue on GitHub .
The Git repo for this module can be found here : http : / / aka . ms / PowerShellForGitHub
. PARAMETER OwnerName
Owner of the repository .
If not supplied here , the DefaultOwnerName configuration property value will be used .
. PARAMETER RepositoryName
Name of the repository .
If not supplied here , the DefaultRepositoryName configuration property value will be used .
. PARAMETER Uri
Uri for the repository .
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
them individually .
. PARAMETER Title
The title of the issue
. PARAMETER Body
The contents of the issue
. PARAMETER Assignee
Login ( s ) for Users to assign to the issue .
. PARAMETER Milestone
2020-05-08 01:04:51 +03:00
The number of the milestone to associate this issue with .
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. PARAMETER Label
Label ( s ) to associate with this issue .
2019-01-16 22:18:24 +03:00
. PARAMETER MediaType
The format in which the API will return the body of the issue .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Raw - Return the raw markdown body .
Response will include body .
This is the default if you do not pass any specific media type .
Text - Return a text only representation of the markdown body .
Response will include body_text .
Html - Return HTML rendered from the body ' s markdown .
Response will include body_html .
Full - Return raw , text and HTML representations .
Response will include body , body_text , and body_html .
2019-01-16 22:18:24 +03:00
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. PARAMETER AccessToken
If provided , this will be used as the AccessToken for authentication with the
REST Api . Otherwise , will attempt to use the configured value or will run unauthenticated .
. PARAMETER NoStatus
If this switch is specified , long-running commands will run on the main thread
with no commandline status update . When not specified , those commands run in
the background , enabling the command prompt to provide status information .
If not supplied here , the DefaultNoStatus configuration property value will be used .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. INPUTS
GitHub . Branch
GitHub . Content
GitHub . Event
GitHub . Issue
GitHub . IssueComment
GitHub . Label
GitHub . Milestone
GitHub . PullRequest
GitHub . Project
GitHub . ProjectCard
GitHub . ProjectColumn
GitHub . Release
GitHub . Repository
. OUTPUTS
GitHub . Issue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. EXAMPLE
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
New-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Title 'Test Issue'
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
#>
[ CmdletBinding (
SupportsShouldProcess ,
2020-05-08 01:04:51 +03:00
DefaultParameterSetName = 'Elements' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ OutputType ( { $script:GitHubIssueTypeName } ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSShouldProcess " , " " , Justification = " Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently. " ) ]
param (
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $OwnerName ,
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $RepositoryName ,
[ Parameter (
Mandatory ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
ValueFromPipelineByPropertyName ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
ParameterSetName = 'Uri' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Alias ( 'RepositoryUrl' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Uri ,
[ Parameter ( Mandatory ) ]
[ ValidateNotNullOrEmpty ( ) ]
[ string ] $Title ,
[ string ] $Body ,
[ string[] ] $Assignee ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter ( ValueFromPipelineByPropertyName ) ]
[ Alias ( 'MilestoneNumber' ) ]
2019-03-15 14:17:02 +03:00
[ int64 ] $Milestone ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string[] ] $Label ,
2019-01-16 22:18:24 +03:00
[ ValidateSet ( 'Raw' , 'Text' , 'Html' , 'Full' ) ]
[ string ] $MediaType = 'Raw' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $AccessToken ,
[ switch ] $NoStatus
)
2018-11-20 00:07:05 +03:00
Write-InvocationLog
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2018-11-20 00:07:05 +03:00
$elements = Resolve-RepositoryElements
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$OwnerName = $elements . ownerName
$RepositoryName = $elements . repositoryName
$telemetryProperties = @ {
'OwnerName' = ( Get-PiiSafeString -PlainText $OwnerName )
'RepositoryName' = ( Get-PiiSafeString -PlainText $RepositoryName )
}
$hashBody = @ {
'title' = $Title
}
if ( $PSBoundParameters . ContainsKey ( 'Body' ) ) { $hashBody [ 'body' ] = $Body }
if ( $PSBoundParameters . ContainsKey ( 'Assignee' ) ) { $hashBody [ 'assignees' ] = @ ( $Assignee ) }
if ( $PSBoundParameters . ContainsKey ( 'Milestone' ) ) { $hashBody [ 'milestone' ] = $Milestone }
2018-12-14 06:22:43 +03:00
if ( $PSBoundParameters . ContainsKey ( 'Label' ) ) { $hashBody [ 'labels' ] = @ ( $Label ) }
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$params = @ {
'UriFragment' = " /repos/ $OwnerName / $RepositoryName /issues "
2018-11-30 22:26:13 +03:00
'Body' = ( ConvertTo-Json -InputObject $hashBody )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'Method' = 'Post'
'Description' = " Creating new Issue "" $Title "" on $RepositoryName "
2020-04-03 21:13:53 +03:00
'AcceptHeader' = ( Get-MediaAcceptHeader -MediaType $MediaType -AsJson -AcceptHeader $symmetraAcceptHeader )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'AccessToken' = $AccessToken
'TelemetryEventName' = $MyInvocation . MyCommand . Name
'TelemetryProperties' = $telemetryProperties
2018-11-20 00:07:05 +03:00
'NoStatus' = ( Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
return ( Invoke-GHRestMethod @params | Add-GitHubIssueAdditionalProperties )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
filter Update-GitHubIssue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
<#
. SYNOPSIS
Create a new Issue on GitHub .
. DESCRIPTION
Create a new Issue on GitHub .
The Git repo for this module can be found here : http : / / aka . ms / PowerShellForGitHub
. PARAMETER OwnerName
Owner of the repository .
If not supplied here , the DefaultOwnerName configuration property value will be used .
. PARAMETER RepositoryName
Name of the repository .
If not supplied here , the DefaultRepositoryName configuration property value will be used .
. PARAMETER Uri
Uri for the repository .
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
them individually .
. PARAMETER Issue
The issue to be updated .
. PARAMETER Title
The title of the issue
. PARAMETER Body
The contents of the issue
. PARAMETER Assignee
Login ( s ) for Users to assign to the issue .
Provide an empty array to clear all existing assignees .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. PARAMETER MilestoneNumber
2020-05-08 01:04:51 +03:00
The number of the milestone to associate this issue with .
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Set to 0 / $null to remove current .
. PARAMETER Label
Label ( s ) to associate with this issue .
Provide an empty array to clear all existing labels .
. PARAMETER State
Modify the current state of the issue .
2019-01-16 22:18:24 +03:00
. PARAMETER MediaType
The format in which the API will return the body of the issue .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Raw - Return the raw markdown body .
Response will include body .
This is the default if you do not pass any specific media type .
Text - Return a text only representation of the markdown body .
Response will include body_text .
Html - Return HTML rendered from the body ' s markdown .
Response will include body_html .
Full - Return raw , text and HTML representations .
Response will include body , body_text , and body_html .
2019-01-16 22:18:24 +03:00
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. PARAMETER AccessToken
If provided , this will be used as the AccessToken for authentication with the
REST Api . Otherwise , will attempt to use the configured value or will run unauthenticated .
. PARAMETER NoStatus
If this switch is specified , long-running commands will run on the main thread
with no commandline status update . When not specified , those commands run in
the background , enabling the command prompt to provide status information .
If not supplied here , the DefaultNoStatus configuration property value will be used .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. INPUTS
GitHub . Branch
GitHub . Content
GitHub . Event
GitHub . Issue
GitHub . IssueComment
GitHub . Label
GitHub . Milestone
GitHub . PullRequest
GitHub . Project
GitHub . ProjectCard
GitHub . ProjectColumn
GitHub . Release
GitHub . Repository
. OUTPUTS
GitHub . Issue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. EXAMPLE
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Update-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 4 -Title 'Test Issue' -State Closed
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
#>
[ CmdletBinding (
SupportsShouldProcess ,
2020-05-08 01:04:51 +03:00
DefaultParameterSetName = 'Elements' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ OutputType ( { $script:GitHubIssueTypeName } ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSShouldProcess " , " " , Justification = " Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently. " ) ]
param (
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $OwnerName ,
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $RepositoryName ,
[ Parameter (
Mandatory ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
ValueFromPipelineByPropertyName ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
ParameterSetName = 'Uri' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Alias ( 'RepositoryUrl' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Uri ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter (
Mandatory ,
ValueFromPipelineByPropertyName ) ]
[ Alias ( 'IssueNumber' ) ]
2019-03-15 14:17:02 +03:00
[ int64 ] $Issue ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Title ,
[ string ] $Body ,
[ string[] ] $Assignee ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ int64 ] $MilestoneNumber ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string[] ] $Label ,
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'Open' , 'Closed' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $State ,
2019-01-16 22:18:24 +03:00
[ ValidateSet ( 'Raw' , 'Text' , 'Html' , 'Full' ) ]
[ string ] $MediaType = 'Raw' ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $AccessToken ,
[ switch ] $NoStatus
)
2018-11-20 00:07:05 +03:00
Write-InvocationLog
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2018-11-20 00:07:05 +03:00
$elements = Resolve-RepositoryElements
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$OwnerName = $elements . ownerName
$RepositoryName = $elements . repositoryName
$telemetryProperties = @ {
'OwnerName' = ( Get-PiiSafeString -PlainText $OwnerName )
'RepositoryName' = ( Get-PiiSafeString -PlainText $RepositoryName )
}
$hashBody = @ { }
if ( $PSBoundParameters . ContainsKey ( 'Title' ) ) { $hashBody [ 'title' ] = $Title }
if ( $PSBoundParameters . ContainsKey ( 'Body' ) ) { $hashBody [ 'body' ] = $Body }
if ( $PSBoundParameters . ContainsKey ( 'Assignee' ) ) { $hashBody [ 'assignees' ] = @ ( $Assignee ) }
2018-12-14 08:57:42 +03:00
if ( $PSBoundParameters . ContainsKey ( 'Label' ) ) { $hashBody [ 'labels' ] = @ ( $Label ) }
2019-01-03 22:11:14 +03:00
if ( $PSBoundParameters . ContainsKey ( 'State' ) ) { $hashBody [ 'state' ] = $State . ToLower ( ) }
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
if ( $PSBoundParameters . ContainsKey ( 'MilestoneNumber' ) )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$hashBody [ 'milestone' ] = $MilestoneNumber
if ( $MilestoneNumber -in ( 0 , $null ) )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
$hashBody [ 'milestone' ] = $null
}
}
$params = @ {
'UriFragment' = " /repos/ $OwnerName / $RepositoryName /issues/ $Issue "
2018-11-30 22:26:13 +03:00
'Body' = ( ConvertTo-Json -InputObject $hashBody )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'Method' = 'Patch'
'Description' = " Updating Issue # $Issue on $RepositoryName "
2020-04-03 21:13:53 +03:00
'AcceptHeader' = ( Get-MediaAcceptHeader -MediaType $MediaType -AsJson -AcceptHeader $symmetraAcceptHeader )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'AccessToken' = $AccessToken
'TelemetryEventName' = $MyInvocation . MyCommand . Name
'TelemetryProperties' = $telemetryProperties
2018-11-20 00:07:05 +03:00
'NoStatus' = ( Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
return ( Invoke-GHRestMethod @params | Add-GitHubIssueAdditionalProperties )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
filter Lock-GitHubIssue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
<#
. SYNOPSIS
Lock an Issue or Pull Request conversation on GitHub .
. DESCRIPTION
Lock an Issue or Pull Request conversation on GitHub .
The Git repo for this module can be found here : http : / / aka . ms / PowerShellForGitHub
. PARAMETER OwnerName
Owner of the repository .
If not supplied here , the DefaultOwnerName configuration property value will be used .
. PARAMETER RepositoryName
Name of the repository .
If not supplied here , the DefaultRepositoryName configuration property value will be used .
. PARAMETER Uri
Uri for the repository .
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
them individually .
. PARAMETER Issue
The issue to be locked .
. PARAMETER Reason
The reason for locking the issue or pull request conversation .
. PARAMETER AccessToken
If provided , this will be used as the AccessToken for authentication with the
REST Api . Otherwise , will attempt to use the configured value or will run unauthenticated .
. PARAMETER NoStatus
If this switch is specified , long-running commands will run on the main thread
with no commandline status update . When not specified , those commands run in
the background , enabling the command prompt to provide status information .
If not supplied here , the DefaultNoStatus configuration property value will be used .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. INPUTS
GitHub . Branch
GitHub . Content
GitHub . Event
GitHub . Issue
GitHub . IssueComment
GitHub . Label
GitHub . Milestone
GitHub . PullRequest
GitHub . Project
GitHub . ProjectCard
GitHub . ProjectColumn
GitHub . Release
GitHub . Repository
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. EXAMPLE
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Lock-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 4 -Title 'Test Issue' -Reason Spam
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
#>
[ CmdletBinding (
SupportsShouldProcess ,
2020-05-08 01:04:51 +03:00
DefaultParameterSetName = 'Elements' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSShouldProcess " , " " , Justification = " Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently. " ) ]
param (
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $OwnerName ,
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $RepositoryName ,
[ Parameter (
Mandatory ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
ValueFromPipelineByPropertyName ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
ParameterSetName = 'Uri' ) ]
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Alias ( 'RepositoryUrl' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Uri ,
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter (
Mandatory ,
ValueFromPipelineByPropertyName ) ]
[ Alias ( 'IssueNumber' ) ]
2019-03-15 14:17:02 +03:00
[ int64 ] $Issue ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2019-01-03 22:11:14 +03:00
[ ValidateSet ( 'OffTopic' , 'TooHeated' , 'Resolved' , 'Spam' ) ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
[ string ] $Reason ,
[ string ] $AccessToken ,
[ switch ] $NoStatus
)
2018-11-20 00:07:05 +03:00
Write-InvocationLog
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
2018-11-20 00:07:05 +03:00
$elements = Resolve-RepositoryElements
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$OwnerName = $elements . ownerName
$RepositoryName = $elements . repositoryName
$telemetryProperties = @ {
'OwnerName' = ( Get-PiiSafeString -PlainText $OwnerName )
'RepositoryName' = ( Get-PiiSafeString -PlainText $RepositoryName )
}
$hashBody = @ {
'locked' = $true
}
if ( $PSBoundParameters . ContainsKey ( 'Reason' ) )
{
2019-01-03 22:11:14 +03:00
$reasonConverter = @ {
'OffTopic' = 'off-topic'
'TooHeated' = 'too heated'
'Resolved' = 'resolved'
'Spam' = 'spam'
}
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
$telemetryProperties [ 'Reason' ] = $Reason
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$hashBody [ 'lock_reason' ] = $reasonConverter [ $Reason ]
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
$params = @ {
'UriFragment' = " /repos/ $OwnerName / $RepositoryName /issues/ $Issue /lock "
2018-11-30 22:26:13 +03:00
'Body' = ( ConvertTo-Json -InputObject $hashBody )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'Method' = 'Put'
'Description' = " Locking Issue # $Issue on $RepositoryName "
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
'AcceptHeader' = $script:sailorVAcceptHeader
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
'AccessToken' = $AccessToken
'TelemetryEventName' = $MyInvocation . MyCommand . Name
'TelemetryProperties' = $telemetryProperties
2018-11-20 00:07:05 +03:00
'NoStatus' = ( Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus )
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
return Invoke-GHRestMethod @params
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
filter Unlock-GitHubIssue
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
{
<#
. SYNOPSIS
Unlocks an Issue or Pull Request conversation on GitHub .
. DESCRIPTION
Unlocks an Issue or Pull Request conversation on GitHub .
The Git repo for this module can be found here : http : / / aka . ms / PowerShellForGitHub
. PARAMETER OwnerName
Owner of the repository .
If not supplied here , the DefaultOwnerName configuration property value will be used .
. PARAMETER RepositoryName
Name of the repository .
If not supplied here , the DefaultRepositoryName configuration property value will be used .
. PARAMETER Uri
Uri for the repository .
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
them individually .
. PARAMETER Issue
The issue to be unlocked .
. PARAMETER AccessToken
If provided , this will be used as the AccessToken for authentication with the
REST Api . Otherwise , will attempt to use the configured value or will run unauthenticated .
. PARAMETER NoStatus
If this switch is specified , long-running commands will run on the main thread
with no commandline status update . When not specified , those commands run in
the background , enabling the command prompt to provide status information .
If not supplied here , the DefaultNoStatus configuration property value will be used .
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
. INPUTS
GitHub . Branch
GitHub . Content
GitHub . Event
GitHub . Issue
GitHub . IssueComment
GitHub . Label
GitHub . Milestone
GitHub . PullRequest
GitHub . Project
GitHub . ProjectCard
GitHub . ProjectColumn
GitHub . Release
GitHub . Repository
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
. EXAMPLE
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Unlock-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 4
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
#>
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ CmdletBinding (
SupportsShouldProcess ,
DefaultParameterSetName = 'Elements' ) ]
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSShouldProcess " , " " , Justification = " Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently. " ) ]
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSReviewUnusedParameter " , " " , Justification = " One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1. " ) ]
param (
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $OwnerName ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter ( ParameterSetName = 'Elements' ) ]
[ string ] $RepositoryName ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter (
Mandatory ,
ValueFromPipelineByPropertyName ,
ParameterSetName = 'Uri' ) ]
[ Alias ( 'RepositoryUrl' ) ]
[ string ] $Uri ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ Parameter (
Mandatory ,
ValueFromPipelineByPropertyName ) ]
[ Alias ( 'IssueNumber' ) ]
[ int64 ] $Issue ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ string ] $AccessToken ,
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
[ switch ] $NoStatus
)
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
Write-InvocationLog
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$elements = Resolve-RepositoryElements
$OwnerName = $elements . ownerName
$RepositoryName = $elements . repositoryName
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$telemetryProperties = @ {
'OwnerName' = ( Get-PiiSafeString -PlainText $OwnerName )
'RepositoryName' = ( Get-PiiSafeString -PlainText $RepositoryName )
}
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
$params = @ {
'UriFragment' = " /repos/ $OwnerName / $RepositoryName /issues/ $Issue /lock "
'Method' = 'Delete'
'Description' = " Unlocking Issue # $Issue on $RepositoryName "
'AcceptHeader' = $script:sailorVAcceptHeader
'AccessToken' = $AccessToken
'TelemetryEventName' = $MyInvocation . MyCommand . Name
'TelemetryProperties' = $telemetryProperties
'NoStatus' = ( Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus )
}
return Invoke-GHRestMethod @params
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
Adding complete Pipeline support to the entire module (#242)
# Description
Comprehensively adds pipeline support throughout the entire module
This change required examining every method, and in some cases a few breaking changes (noted below) had to be introduced in order to make support work consistently end-to-end. UT's were added for every function, which resuled in a few bugs that were identified and fixed (also noted below).
## Breaking changes
### Unavoidable Breaks
* `Get-GitHubRepositoryBranch`: `Name` parameter is now `BranchName`.
> A `GitHub.Repository` object has a `name` property which is the name of the repo. Piping in the repo object to this method would confuse it, making it search for a branch with the name of the repo, as opposed to the desired effect of just listing out all branches in the repo.
* `*-GitHub*Label`: `Name` parameter is now `Label`.
> Similar to above.
> `Name` was too generic and was causing unintended conflicts when passing in certain objects over the pipeline (like a `GitHub.Repository`) which also has a `name` property, making it impossible to pipe in a repository to list all labels (since it was trying to query for a label in that repository named the same as the repo.
* `*-GitHubLabel`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `*-GitHubIssue`: `Milestone` parameter is now `MilestoneNumber`.
> A `GitHub.Issue` contains a `milestone` object property, and PowerShell was complaining that there was no way to convert that to an `[int64]` when an Issue was passed in via the pipeline. The only way to avoid this was to use `MilestoneNumber` which is the name of the property we add to `GitHub.Milestone` objects, and it's what we alias to in all other methods that interact with milestones.
* `Get-GitHubLicense`: `Name` parameter is now `Key`.
> The `key` is what you can query against, but a License object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `Get-GitHubCodeOfConduct`: `Name` parameter is now `Key`.
> Similar to above.
> The `key` is what you can query against, but a Code of Conduct object has _both_ a `name` and a `key` property, which caused piped object queries to fail with the existing parameter name.
* `New-ProjectCard`: Signature has changed. Instead of specifying `ContentId` and `ContentType`, you now just directly specify either `IssueId` or `PullRequestId`.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
* `Get-GitHubUserContextualInformation`: Signature has changed. Instead of specifying `SubjectId` and `SubjectType`, you now just directly specify either `OrganizationId`, `RepositoryId`, `IssueId` or `PullRequestId`.
> Similar to above.
> Pipeline input would not have worked without this change. Additionally, this simply provides a cleaner interface for users in general, requiring one less input.
### Breaks With Workarounds
* A number of changes to the Comments functions
* `GitHubComments.ps1` was renamed to `GitHubIssueComments.ps1` given that there are 5 different types of comments, these functions focus on `Issue` comments, and there doesn't currently appear to be a path forward for creating a single unified API set for all comment types.
* All of these methods were renamed from `*-GitHubComment` to `*-GitHubIssueComment`, however they were also aliased back to their previous names (for now). You should really migrate to these new names however.
* The main parameter was renamed from `CommentId` to `Comment`, however it was aliased back to `CommentId`.
* `*-GitHubProject`: `ArchivedState` parameter is now `State` (but aliased back to `ArchivedState` to help with migration).
* `*-GitHubProject`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `*-GitHubProjectColumn`: `Name` parameter is now `ColumnName` (but aliased back to `Name`)
* `Move-GitHubProjectCard`: `ColumnId` parameter is now `Column` (but aliased back to `ColumnId` to support pipeline input).
* `Get-GitHubRelease`: `ReleaseId` parameter is now `Release` (but aliased back to `ReleaseId` to support pipeline input).
* `Rename-GitHubRepository` has been effectively deprectaed. It was built on top of the same endpoint that `Set-GitHubRepository` uses, but was only modifying a single property (the name). For now, the function remains, but it now just internally calls into `Set-GitHubRepository` to perform the same action.
* `Set-GitHubRepositoryTopic`: `Name` parameter is now `Topic` (but aliased back to `Name`).
* `Get-GitHubUser`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
* `Get-GitHubUserContextualInformation`: `User` parameter is now `UserName` (but aliased back to `User` and `Name`).
## Bug Fixes:
* Events had been using a typo'd version of the `sailor-v` AcceptHeader. This was fixed as part of the migration to using the AcceptHeader constants.
* `Lock-GitHubIssue` was not correctly providing the `lock_reason` value to the API, so that metadata was getting lost. This was caught by new UT's and then fixed.
* `Update-GitHubLabel` was modified to accept colors both with and without a leading # sign, just like `New-GitHubLabel` already supported.
## New Features:
* `Get-GitHubGitIgnore` has a new `RawContent` switch which allows you to directly get back the content of the actual .gitignore file.
* `Set-GitHubRepository` has been updated to allow users to change the name (rename) the repository at the same time as making any of their other changes. If a new name has been specified, users will be required to confirm the change, or to specify `-Confirm:$false` and/or `-Force` to avoid the confirmation.
* `Get-GitHubRepositoryCollaborator` has gained a new parameter `Affiliation` allowing you to filter which collaborators you're interested in querying for.
## Minor updates:
* Fixed the casing of the "microsoft" OwnerName in any examples
* Fixed the casing of `GitHub` in the `Assignee` method names (was `Github` intead of `GitHub`
* Added new configuration property (`DisablePipelineSupport`) to assist with pipeline development
* All `AcceptHeader` usage has migrated to using script-wide constants
* `Split-GitHubUri` can now return both components in a single function call if no switch is specified.
* Added `Join-GitHubUri` which can reverse what `Split-GitHubUri` does, based on the configured `ApiHostName`.
* Adds type information (via `.OUTPUTS` and `[OutputType()]` for every function.
* Documentation updates reflecting the new pipeline support.
## Test changes:
* `Set-StrictMode -Version 1.0` has been specified for all tests to catch access to undeclared variables (which should help catch common typo errors)
* The workarounds for PSScriptAnalyzer's false complaint for rule `PSUseDeclaredVarsMoreThanAssignments` have been removed, and all test files now suppress that rule.
* A test file now exists for every module file, and some tests were moved around to the appropriate file (away from GitHubAnalytics.tests.ps1 which had previously been a dumping ground for tests).
* A _substantial_ number of new tests have been added. Every function should now be tested with limited exceptions (like for Organizations and Teams where we don't yet have the support in the module to get the account in the appropriate state to be able to query with those existing functions).
> Note: These tests fully pass with Pester 4.10.1. Some additional work may be done prior to merging to get them passing with Pester 5.0, but the priority is to get this merged into master soon in order to unblock the pipeline of existing pull requests that have been waiting on this change.
#### Issues Fixed
- Fixes #63
#### References
[The whole API set](https://developer.github.com/v3/)
2020-06-18 08:26:59 +03:00
filter Add-GitHubIssueAdditionalProperties
{
<#
. SYNOPSIS
Adds type name and additional properties to ease pipelining to GitHub Issue objects .
. PARAMETER InputObject
The GitHub object to add additional properties to .
. PARAMETER TypeName
The type that should be assigned to the object .
. INPUTS
[ PSCustomObject ]
. OUTPUTS
GitHub . Issue
#>
[ CmdletBinding ( ) ]
[ Diagnostics . CodeAnalysis . SuppressMessageAttribute ( " PSUseSingularNouns " , " " , Justification = " Internal helper that is definitely adding more than one property. " ) ]
param (
[ Parameter (
Mandatory ,
ValueFromPipeline ) ]
[ AllowNull ( ) ]
[ AllowEmptyCollection ( ) ]
[ PSCustomObject[] ] $InputObject ,
[ ValidateNotNullOrEmpty ( ) ]
[ string ] $TypeName = $script:GitHubIssueTypeName
)
foreach ( $item in $InputObject )
{
# Pull requests are _also_ issues. A pull request that is retrieved through the
# Issue endpoint will also have a 'pull_request' property. Let's make sure that
# we mark it up appropriately.
if ( $null -ne $item . pull_request )
{
$null = Add-GitHubPullRequestAdditionalProperties -InputObject $item
Write-Output $item
continue
}
$item . PSObject . TypeNames . Insert ( 0 , $TypeName )
if ( -not ( Get-GitHubConfiguration -Name DisablePipelineSupport ) )
{
$elements = Split-GitHubUri -Uri $item . html_url
$repositoryUrl = Join-GitHubUri @elements
Add-Member -InputObject $item -Name 'RepositoryUrl' -Value $repositoryUrl -MemberType NoteProperty -Force
Add-Member -InputObject $item -Name 'IssueId' -Value $item . id -MemberType NoteProperty -Force
Add-Member -InputObject $item -Name 'IssueNumber' -Value $item . number -MemberType NoteProperty -Force
@ ( 'assignee' , 'assignees' , 'user' ) |
ForEach-Object {
if ( $null -ne $item . $_ )
{
$null = Add-GitHubUserAdditionalProperties -InputObject $item . $_
}
}
if ( $null -ne $item . labels )
{
$null = Add-GitHubLabelAdditionalProperties -InputObject $item . labels
}
if ( $null -ne $item . milestone )
{
$null = Add-GitHubMilestoneAdditionalProperties -InputObject $item . milestone
}
if ( $null -ne $item . closed_by )
{
$null = Add-GitHubUserAdditionalProperties -InputObject $item . closed_by
}
if ( $null -ne $item . repository )
{
$null = Add-GitHubRepositoryAdditionalProperties -InputObject $item . repository
}
}
Write-Output $item
}
Module restructure to v0.2.0
+ Significant restructing and refactoring of entire module to make future expansion easier.
+ Significant documentation updates ([CHANGELOG](./CHANGELOG.md), [CONTRIBUTING.md](./CONTRIBUTING.md),
[GOVERNANCE.md](./GOVERNANCE.md), [README.md](./README.md), [USAGE.md](./USAGE.md))
+ Added `Set-GitHubAuthentication` (and related methods) for securely caching the Access Token
+ Added `Set-GitHubConfiguration` (and related methods) to enable short and long-term configuration
of the module.
+ Added ability to asynchronously see status update of REST requests.
+ Added logging and telemetry to the module (each can be disabled if desired).
+ Tests now auto-configure themselves across whatever account information is supplied in
[Tests/Config/Settings.ps1](./Tests/Config/Settings.ps1)
+ Added support for a number of additional GitHub API's:
+ All [Miscellaneous API's](https://developer.github.com/v3/misc/)
+ Ability to fully query, update, remove, lock, and unlock Issues.
+ Enhanced pull request querying support
+ Ability tofully query, create, and remove Repositories, as well as transfer ownership,
get tags, get/set topic and current used programming languages.
+ Enhanced user query support as well as being able update information for the current user.
* Made parameter ordering consistent across all functions (OwnerName is now first, then RepositoryName)
* Normalized all parameters to use SentenceCase
* All functions that can take a Uri or OwnerName/RepositoryName now support both options.
* Made all parameter names consistent across functions:
* `GitHubAccessToken` -> `AccessToken`
* `RepositoryUrl` -> `Uri`
* `Organization` -> `OrganizationName`
* `Repository` -> `RepositoryName`
* `Owner` -> `OwnerName`
* Normalized usage of Verbose, Info and Error streams
- `New-GitHubLabels` was renamed to `Set-GitHubLabel` and can now optionally take in the labels
to apply to the Repository.
- `Get-GitHubIssueForRepository` has been removed and replaced with `Get-GitHubIssue`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/closed date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubIssue` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-issues).
- `Get-GitHubWeeklyIssueForRepository` has been removed and functionally replaced by `Group-GitHubIssue`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-issues)
- `Get-GitHubTopIssueRepository` has been removed. We have [updated examples](USAGE.md#querying-issues)
for how to accomplish the same scenario.
- `Get-GitHubPullRequestForRepository` has been removed and replaced with `Get-GitHubPullRequest`.
The key difference between these two is that it no longer accepts multiple repositories as single
input, and filtering on creation/merged date can be done after the fact piping the results into
`Where-Object` now that the returned objects from `Get-GitHubPullRequest` have actual `[DateTime]` values
for the date properties. For an updated example of doing this, refer to [example usage](USAGE.md#querying-pull-requests).
- `Get-GitHubWeeklyPullRequestForRepository` has been removed and functionally replaced by `Group-GitHubPullRequest`.
For an updated example of using it, refer to [example usage](USAGE.md#querying-pull-requests)
- `Get-GitHubTopPullRequestRepository` has been removed. We have [updated examples](USAGE.md#querying-pull-requests)
for how to accomplish the same scenario.
- `Get-GitHubRepositoryNameFromUrl` and `GitHubRepositoryOwnerFromUrl` have been removed and
functionally replaced by `Split-GitHubUri`
- `Get-GitHubRepositoryUniqueContributor` has been removed. We have an
[updated example](USAGE.md#querying-contributors) for how to accomplish the same scenario.
- `GitHubOrganizationRepository` has been removed. You can now retrieve repositories for an
organization via `Get-GitHubRepository -OrganizationName <name>`.
- `Get-GitHubAuthenticatedUser` has been replaced with `Get-GitHubUser -Current`.
Fixes Issue #34: Warning output on import is being written out twice
Fixes Issue #33: TLS error in Get-GitHubIssueForRepository : Failed to execute query with exception
Fixes Issue #26: Token in template file
Fixes Issue #24: Add a command for configuration
2018-10-31 09:14:28 +03:00
}
