DscCommunity Labels

README.md

License

This gist and all the files it contains is under MIT licens.

Setup instructions

NOTE: Run under PowerShell Core. In a recent change to the module PSGitHUb, it no longer works under Windows PowerShell.

1. Install the module from PowerShell Gallery Install-Module -Name PSGitHub (Project site: https://github.com/pcgeek86/PSGitHub).
2. Run Import-Module -Name PSGitHub.
3. Run the following to set the GitHub token (create it in your account on GitHub).

   # Token parameter is used on all the PSGitHub cmdlets. Token is a secure string.
   $PSDefaultParameterValues = @{
       "*-GitHub*:Token" = ("<personal_access_token>" | ConvertTo-SecureString -AsPlainText -Force)
   }

4. Open the script 'DscCommunity-Labels.ps1' and update the information under all the 'TODO:' markers.
5. Run the script 'DscCommunity-Labels.ps1'. To verify what will happen, start by running the script with -WhatIf, i.e. .\DscCommunity-Labels.ps1 -WhatIf -Verbose. Use the parameter -Confirm:$false to override the confirm dialogs.
6. Clear the token from $PSDefaultParameterValues by closing the session or running:

   $PSDefaultParameterValues.Remove('*-GitHub*:Token')

WARNING: When you remove a label it will also be remove from all issues and pull requests. Make sure that it is not used any longer.

DscCommunity-Labels.ps1

<#
    .SYNOPSIS
        Script to add and update labels according how they are defined in the
        DSC Resource Kit.
#>
[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
param ()

<#
    TODO: Add all your repositories to the array.
#>
$repositories = @(
    @{
        Owner = 'PowerShell'
        Name = 'xFailOverCluster'
    }
    
    @{
        Owner = 'PowerShell'
        Name = 'SqlServerDsc'
    }
)

#region Labels
<#
    # TODO: Add any new labels to this array.

    Array of hash tables, on hash table for each label.

    Syntax:
    @{
        Name = [String]
        Description = [String]
        Color = [String]
        Action = [String] { Update | Remove | Replace }
        [ReplacedBy = [String]]
    }

    Name: The name of the label

    Description: The description of the label. Max 100 chars (limited by GitHub),

    Color: Color of the label, without the '#'.

    Action: Either Update, Remove or Replace.
        Update: The label will be updated if it differs.
        Remove: The label will be removed (also removed from any issues and PR's).
        Replace: The label is being replaced by another label with the label name
                 that is assigned to 'ReplacedBy'. If the label in 'ReplacedBy'
                 already exist, then the label being replaced is removed.

    ReplacedBy: The label from which to get the information to write over
                (replace) this label.

#>
$dscResourceKitLabels = @(
    @{ Name = 'abandoned'; Description = 'The pull request has been abandoned.'; Color = 'ffffff'; Action = 'Update' }
    @{ Name = 'blocking release'; Description = 'The issue or pull request is blocking the next release. Higher priority than label ''High priority''.'; Color = '800000'; Action = 'Update' }
    @{ Name = 'breaking change'; Description = 'When used on an issue, the issue has been determined to be a breaking change.'; Color = 'ff9900'; Action = 'Update' }
    @{ Name = 'bug'; Description = 'The issue is a bug.'; Color = 'ee0701'; Action = 'Update' }
    @{ Name = 'by design'; Description = 'The issue is describing an expect behavior.'; Color = 'ffffff'; Action = 'Update' }
    @{ Name = 'closed by author'; Description = 'The issue or pull request was closed by the author.'; Color = 'ffffff'; Action = 'Update' }
    @{ Name = 'discussion'; Description = 'The issue is a discussion.'; Color = '993399'; Action = 'Update' }
    @{ Name = 'documentation'; Description = 'The issue is related to documentation only.'; Color = 'c5def5'; Action = 'Update' }
    @{ Name = 'duplicate'; Description = 'The issue or PR is the duplicate of another.'; Color = 'ffffff'; Action = 'Update' }
    @{ Name = 'easy fix'; Description = ''; Color = ''; Action = 'Replace'; ReplacedBy = 'good first issue' }
    @{ Name = 'good first issue'; Description = 'The issue should be easier to fix and can be taken up by a beginner to learn to contribute on GitHub'; Color = '5319e7'; Action = 'Update' }
    @{ Name = 'enhancement'; Description = 'The issue is an enhancement request.'; Color = 'c5def5'; Action = 'Update' }
    @{ Name = 'external'; Description = 'The issue cannot be resolved within the DSC Resource Kit.'; Color = 'ffffff'; Action = 'Update' }
    @{ Name = 'help wanted'; Description = 'The issue is up for grabs for anyone in the community.'; Color = '128A0C'; Action = 'Update' }
    @{ Name = 'high priority'; Description = 'The issue or PR should be resolved first. It is of less priority than the label ''Blocking Release''.'; Color = 'ffcc99'; Action = 'Update' }
    @{ Name = 'in progress'; Description = 'The issue is being actively worked on by someone.'; Color = '99ffcc'; Action = 'Update' }
    @{ Name = 'needs investigation'; Description = 'The issue needs to be investigated by the maintainers or/and the community.'; Color = 'ffff99'; Action = 'Update' }
    @{ Name = 'needs more information'; Description = 'The issue needs more information from the author or the community.'; Color = 'ffff99'; Action = 'Update' }
    @{ Name = 'needs review'; Description = 'The pull request needs a code review.'; Color = '99ff33'; Action = 'Update' }
    @{ Name = 'not fixed'; Description = 'The issue was closed without being fixed.'; Color = 'ffffff'; Action = 'Update' }
    @{ Name = 'on hold'; Description = 'The issue or pull request has been put on hold by a maintainer.'; Color = '1e1e7b'; Action = 'Update' }
    @{ Name = 'question'; Description = 'The issue is a question.'; Color = 'cc317c'; Action = 'Update' }
    @{ Name = 'ready for merge'; Description = 'The pull request was approved by the community and is ready to be merged by a maintainer.'; Color = '215e82'; Action = 'Update' }
    @{ Name = 'resolved in dev'; Description = "A fix has been merged into the dev-branch but the issue is still open and awaits next release."; Color = '215e82'; Action = 'Update' }
    @{ Name = 'resource proposal'; Description = 'The issue is proposing a new resource in the resource module.'; Color = 'fbca04'; Action = 'Update' }
    @{ Name = 'stale'; Description = "The issue or pull request was marked as stale because there hasn't been activity from the community."; Color = 'cccccc'; Action = 'Update' }
    @{ Name = 'tests'; Description = 'The issue or pull request is about tests only.'; Color = 'c5def5'; Action = 'Update' }
    @{ Name = 'updated by author'; Description = 'The pull request was last updated by the author.'; Color = 'e3f1dA'; Action = 'Update' }
    @{ Name = 'waiting for the author'; Description = ''; Color = ''; Action = 'Replace'; ReplacedBy = 'Waiting for author response' }
    @{ Name = 'waiting for author response'; Description = 'The pull request is waiting for the author to respond to comments in the pull request.'; Color = 'ffff99'; Action = 'Update' }
    @{ Name = 'waiting for code fix'; Description = 'A review left open comments, and the pull request is waiting for changes to be pushed by the author.'; Color = 'ffff99'; Action = 'Update' }
    @{ Name = 'Linux'; Description = "This targets Linux platform-family."; Color = '221A3e'; Action = 'Update' }
    @{ Name = 'Windows'; Description = "This targets Windows platform-family."; Color = '221A3e'; Action = 'Update' }
    @{ Name = 'macOS'; Description = "This targets macOS platform-family."; Color = '221A3e'; Action = 'Update' }
)
#endregion Labels

foreach ($repository in $repositories)
{
    #region Get existing labels
    $existingLabels = @()
    $pageNumber = 0

    do
    {
        $pageNumber++
        $pageOfLabels = Get-GitHubLabel -Owner $repository.Owner -Repository $repository.Name -Page $pageNumber
        if ($pageOfLabels.Count -ne 0)
        {
            $existingLabels += $pageOfLabels
        }
    } while ($pageOfLabels.Count -ne 0)
    #endregion Get existing labels

    #region Replace labels
    <#
        1. Check if the old label being replaced exist.
        2. Check if the new label, that the old label is being replaced with,
           exist.
        3. if neither exist, create the new label.
        4. If the old label exist, replace with information of the label
           assigned to ReplacedBy.
        5. if both label exist, remove the old label.
        6. If only the new label exist, do nothing, it will be handled in
           the update label logic.
    #>

    $labelsToReplace = $dscResourceKitLabels | Where-Object -FilterScript {
        $_.Action -in ('Replace')
    }

    if ($labelsToReplace)
    {
        Write-Verbose -Message 'Replacing labels.'
    }

    foreach ($label in $labelsToReplace)
    {
        $oldLabelExist = -not [System.String]::IsNullOrEmpty((
                $dscResourceKitLabels |
                    Where-Object -FilterScript {
                    $label.Name -in ($existingLabels.Name)
                }
            ))

        $newLabelExist = -not [System.String]::IsNullOrEmpty((
                $dscResourceKitLabels |
                    Where-Object -FilterScript {
                    $label.ReplacedBy -in ($existingLabels.Name)
                }
            ))

        $newLabel = $dscResourceKitLabels | Where-Object -FilterScript {
            $_.Name -eq $label.ReplacedBy
        }

        if (-not $newLabel)
        {
            throw ('The label ''{0}'', which should replace the label ''{1}'', does not exist in the array of DSC Resource Kit labels. Could not get information about the label ''{0}''.' -f $label.ReplacedBy, $label.Name)
        }

        if ($oldLabelExist -and -not $newLabelExist)
        {
            <#
                The old label being replaced exist, and the new label does not
                exist.
                Update the old label with the new label information.
            #>
            $shouldProcessCaption = 'Update GitHub label with the new information'
            $shouldProcessDescription = '[{0}/{1}] Renaming the old label ''{2}'' to the new name ''{3}''.' -f $repository.Owner, $repository.Name, $label.Name, $label.ReplacedBy
            $shouldProcessWarning = '[{0}/{1}] Do you want to rename the old label ''{2}'' to the new name ''{3}''?' -f $repository.Owner, $repository.Name, $label.Name, $label.ReplacedBy


            if ($PSCmdlet.ShouldProcess($shouldProcessDescription, $shouldProcessWarning, $shouldProcessCaption))
            {
                $setGitHubLabelParameters = @{
                    Owner       = $repository.Owner
                    Repository  = $repository.Name
                    Name        = $label.Name
                    NewName     = $newLabel.Name
                    Color       = $newLabel.Color
                    Description = $newLabel.Description
                }

                Set-GitHubLabel @setGitHubLabelParameters -ErrorAction 'Stop' -Confirm:$false | Out-Null
            }

            <#
                We have to update existing label in the array $existingLabels.
                This is so that the label is checked to be updated instead of
                being created. It would try to create an already existing label
                if this is not done.
                We could have fetch the correct labels from GitHb again, but
                this saves a couple of API calls.
            #>
            $existingLabelToBeUpdated = $existingLabels | Where-Object -FilterScript { $_.Name -eq $label.Name }
            $existingLabelToBeUpdated.name = $newLabel.Name
            $existingLabelToBeUpdated.color = $newLabel.Color
            $existingLabelToBeUpdated.description = $newLabel.Description
        }
        elseif (-not $oldLabelExist -and -not $newLabelExist)
        {
            <#
                Neither the old label the new label exist.
                The next step will create the new label.
            #>
        }
        elseif ($oldLabelExist -and $newLabelExist)
        {
            <#
                Both the old label the new label exist.
                Remove the old label. Updating the new label will be handled by
                the update logic later.
            #>
            $shouldProcessCaption = 'Remove old GitHub label'
            $shouldProcessDescription = '[{0}/{1}] Both new label ''{3}'', and the old label ''{2}'', already exist. Removing the old label ''{2}''.' -f $repository.Owner, $repository.Name, $label.Name, $label.ReplacedBy
            $shouldProcessWarning = '[{0}/{1}] Both new label ''{3}'', and the old label ''{2}'', already exist. The old label ''{2}'' can be removed, but the label will also be removed from all issues and pull requests! Do you want to remove the old label ''{2}''?' -f $repository.Owner, $repository.Name, $label.Name, $label.ReplacedBy
            $shouldProcessReasonResult = [System.Management.Automation.ShouldProcessReason]::None

            if ($PSCmdlet.ShouldProcess($shouldProcessDescription, $shouldProcessWarning, $shouldProcessCaption, [ref] $shouldProcessReasonResult))
            {
                $setGitHubLabelParameters = @{
                    Owner       = $repository.Owner
                    Repository  = $repository.Name
                    Name        = $label.Name
                }

                Remove-GitHubLabel @setGitHubLabelParameters -ErrorAction 'Stop' -Confirm:$false | Out-Null
            }

            if ($shouldProcessReasonResult -eq [System.Management.Automation.ShouldProcessReason]::WhatIf)
            {
                Write-Warning -Message ('If removing the label ''{0}'', the label will also be removed from all issues and pull requests! Make sure it isn''t used.' -f $label.Name)
            }
        }
        else
        {
            Write-Verbose -Message ('The old label ''{0}'' being replaced does not exist, but the new label ''{1}'' exist. Updating the new label will be handled, if necessary, by the update logic later.' -f $label.Name, $label.ReplacedBy)
        }
    }
    #endregion Replace labels

    #region Update labels
    $labelsToUpdate = $dscResourceKitLabels | Where-Object -FilterScript {
        $_.Action -notin ('Remove', 'Replace')
    }

    if ($labelsToUpdate)
    {
        Write-Verbose -Message 'Updating or creating labels.'
    }

    foreach ($label in $labelsToUpdate)
    {
        $labelExist = -not [System.String]::IsNullOrEmpty((
                $dscResourceKitLabels |
                    Where-Object -FilterScript {
                    $label.Name -in ($existingLabels.Name)
                }
            ))

        if ($labelExist)
        {
            $currentLabelInformation = $existingLabels |
                                            Where-Object -FilterScript {
                                                $_.Name -ceq $label.Name
                                            }
            <#
                The label exist, check if it needs updating.
            #>
            if ($currentLabelInformation.Color -ne $label.Color `
                -or $currentLabelInformation.Description -cne $label.Description)
            {
                $shouldProcessCaption = 'Update GitHub label with the new information'
                $shouldProcessDescription = '[{0}/{1}] Updating the label ''{2}'' with new information.' -f $repository.Owner, $repository.Name, $label.Name
                $shouldProcessWarning = '[{0}/{1}] Do you want to update the label ''{2}'' with new information?' -f $repository.Owner, $repository.Name, $label.Name

                if ($PSCmdlet.ShouldProcess($shouldProcessDescription, $shouldProcessWarning, $shouldProcessCaption))
                {
                    $setGitHubLabelParameters = @{
                        Owner       = $repository.Owner
                        Repository  = $repository.Name
                        Name        = $label.Name
                        Color       = $label.Color
                        Description = $label.Description
                    }

                    Set-GitHubLabel @setGitHubLabelParameters -ErrorAction 'Stop' -Confirm:$false | Out-Null
                }
            }
            else
            {
                Write-Verbose -Message ('The label ''{0}'' already has the correct information.' -f $label.Name)
            }
        }
        else
        {
            <#
                The label does not exist, create the new label.
            #>
            $shouldProcessCaption = 'Create new GitHub label'
            $shouldProcessDescription = '[{0}/{1}] Creating the new label ''{2}''.' -f $repository.Owner, $repository.Name, $label.Name
            $shouldProcessWarning = '[{0}/{1}] Do you want to create the new label ''{2}''?' -f $repository.Owner, $repository.Name, $label.Name

            if ($PSCmdlet.ShouldProcess($shouldProcessDescription, $shouldProcessWarning, $shouldProcessCaption))
            {
                $setGitHubLabelParameters = @{
                    Owner       = $repository.Owner
                    Repository  = $repository.Name
                    Name        = $label.Name
                    Color       = $label.Color
                    Description = $label.Description
                }

                New-GitHubLabel @setGitHubLabelParameters -ErrorAction 'Stop' -Confirm:$false | Out-Null
            }
        }
    }
    #endregion Update labels

    #region Remove labels
    $labelsToRemove = $dscResourceKitLabels | Where-Object -FilterScript {
        $_.Name -notin ($dscResourceKitLabels.ReplacedBy) `
        -and $_.Action -in ('Remove')
    }

    if ($labelsToRemove)
    {
        Write-Verbose -Message 'Removing labels.'
    }

    foreach ($label in $labelsToRemove)
    {
        $labelExist = -not [System.String]::IsNullOrEmpty((
                $dscResourceKitLabels |
                    Where-Object -FilterScript {
                    $label.Name -in ($existingLabels.Name)
                }
            ))

        if ($labelExist)
        {
            <#
                The label exist, remove it.
            #>
            $shouldProcessCaption = 'Remove GitHub label'
            $shouldProcessDescription = '[{0}/{1}] Removing the label ''{2}''.' -f $repository.Owner, $repository.Name, $label.Name
            $shouldProcessWarning = '[{0}/{1}] The label ''{2}'' can be removed, but the label will also be removed from all issues and pull requests! Do you want to remove the label ''{2}''?' -f $repository.Owner, $repository.Name, $label.Name
            $shouldProcessReasonResult = [System.Management.Automation.ShouldProcessReason]::None

            if ($PSCmdlet.ShouldProcess($shouldProcessDescription, $shouldProcessWarning, $shouldProcessCaption, [ref] $shouldProcessReasonResult))
            {
                $setGitHubLabelParameters = @{
                    Owner       = $repository.Owner
                    Repository  = $repository.Name
                    Name        = $label.Name
                }

                Remove-GitHubLabel @setGitHubLabelParameters -ErrorAction 'Stop' -Confirm:$false | Out-Null
            }

            if ($shouldProcessReasonResult -eq [System.Management.Automation.ShouldProcessReason]::WhatIf)
            {
                Write-Warning -Message ('If removing the label ''{0}'', the label will also be removed from all issues and pull requests! Make sure it isn''t used.' -f $label.Name)
            }
        }
        else
        {
            Write-Verbose -Message ('The label ''{0}'' does not exist, no need to run removal.' -f $label.Name)
        }
    }
    #endregion Remove labels

    #region Additional labels
    $additionalLabels = $existingLabels | Where-Object -FilterScript {
        $_.Name -notin ($dscResourceKitLabels.Name)
    }

    if ($additionalLabels)
    {
        Write-Verbose -Message ('[{0}/{1}] Additional labels in the repository that was ignored: ''{2}''' -f $repository.Owner, $repository.Name, ($additionalLabels.Name -join ''', '''))
    }
    #endregion Additional labels
}

LICENSE

The MIT License (MIT)

Copyright (c) Johan Ljunggren

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.