function Update-Changelog {
    <#
    .SYNOPSIS
        Updates the changelog file with recent commits

    .DESCRIPTION
        This helper function is used to insert recent changes for an upcoming release.

    .Parameter NewVersion
        Provide a valid semver based version tag for the upcoming release like:

        - `v0.0.1-dev1`
        - `v1.0.0`

    .Parameter SkipCleanup
        You can skip the tag update and additional test.

    .INPUTS
        [None] No pipeline input.

    .OUTPUTS
        [None] no pipeline putput.

    .EXAMPLE
        Import-Module -Name DroneHelper; Update-Changelog -NewVersion '0.0.1-dev5'
    #>
    [CmdletBinding()]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
        'PSAvoidUsingInvokeExpression',
        '',
        Justification = 'raw git commands needed'
    )]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
        'PSUseShouldProcessForStateChangingFunctions',
        '',
        Justification = 'system state does not change permanent in temp build clients.'
    )]
    param (
        [Parameter(Mandatory = $true)]
        [ValidatePattern('^(v)?([0-9]+)\.([0-9]+)\.([0-9]+)(-([A-Za-z]+)([0-9]+))?$')]
        [String]$NewVersion,

        [Parameter(Mandatory = $false)]
        [Switch]$SkipCleanup
    )
    process {
        if (-not $SkipCleanup.IsPresent) {
            Invoke-Expression -Command 'git tag -d $(git tag -l)' | Write-Verbose
            Invoke-Expression -Command 'git fetch --tags --prune' | Write-Verbose
            $GitState = Get-GitStatus

            if ($GitState.Branch -eq 'master') {
                Write-Error -Message 'You can nor update the changelog within the master branch!' -ErrorAction Stop
            }
            if (
                ($GitState.BehindBy -ne 0) -or
                ($GitState.AheadBy -ne 0) -or
                ($GitState.HasUntracked -ne $false) -or
                ($GitState.HasWorking -ne $false)
            ) {
                Write-Error -Message 'Your branch is a mess! Cleanup and try it again.' -ErrorAction Stop
            }
        }

        $Repo = Get-RepoPath
        $Tags = Invoke-Expression -Command 'git tag'
        $NormalizedTags = $Tags | Where-Object { $_ -notmatch '-' } | ForEach-Object {
            [PSCustomObject]@{
                tag        = $_
                rawVersion = (
                    ($_ -split '-')[0] -replace 'v', ''
                )
            }
        }
        $LTag = $NormalizedTags | Sort-Object -Property 'rawVersion' | Select-Object -ExpandProperty 'tag' -Last 1
        Write-Debug -Message ('Last tag: {0}' -f $LTag)
        if ($null -eq $LTag) {
            Write-Error -Message 'No tags found!' -ErrorAction 'Stop'
        }
        $Expr = "git log {0}..HEAD --format='- (%h) %s'" -f $LTag
        $Res = Invoke-Expression -Command $Expr
        Write-Debug -Message ('New Changelog: {0}' -f $Res)
        if ($Repo.Changelog.Exists) {
            $Content = Get-Content -Path $Repo.Changelog.Item.FullName
            $Content[2] += "{0}## ``{2}``{0}{0}{1}" -f [Environment]::NewLine, ($Res | Out-String), $NewVersion
            $Content | Out-File -FilePath $Repo.Changelog.Item.FullName -Encoding utf8
            Set-EOL -Path $Repo.Changelog.Item.FullName
        }
        else {
            Write-Error -Message 'Changelog file does not exist!' -ErrorAction Stop
        }
    }
}