From 490d990cee6ea9626e96c307e4fddc3e7c6a7856 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Tue, 22 Jun 2021 18:26:48 -0700 Subject: [PATCH 1/6] Checkout branch in `Update-Version` too --- tools/ReleaseTools.psm1 | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/tools/ReleaseTools.psm1 b/tools/ReleaseTools.psm1 index f65dfbeca1..dd3f56ba3c 100644 --- a/tools/ReleaseTools.psm1 +++ b/tools/ReleaseTools.psm1 @@ -134,6 +134,21 @@ function Get-FirstChangelog { ) } +<# +.SYNOPSIS + Creates and checks out `release/v` if not already on it. +#> +function Update-Branch { + param( + [Parameter(Mandatory)] + [string]$Version + ) + $branch = git branch --show-current + if ($branch -ne "release/v$Version") { + git checkout -b "release/v$Version" + } +} + <# .SYNOPSIS Gets current version from changelog as [semver]. @@ -221,10 +236,7 @@ function Update-Changelog { ) | Set-Content -Encoding utf8NoBOM -Path $ChangelogFile if ($PSCmdlet.ShouldProcess("$RepositoryName/$ChangelogFile", "git")) { - $branch = git branch --show-current - if ($branch -ne "release/$Version") { - git checkout -b "release/$Version" - } + Update-Branch -Version $Version git add $ChangelogFile git commit -m "Update CHANGELOG for $Version" } @@ -311,6 +323,7 @@ function Update-Version { } if ($PSCmdlet.ShouldProcess("$RepositoryName/v$Version", "git commit")) { + Update-Branch -Version $Version git commit -m "Bump version to v$Version" } From 8f0d18ac1fcc9e0b554c92e27980e156cdf24a31 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Tue, 22 Jun 2021 18:27:02 -0700 Subject: [PATCH 2/6] Small fixes --- docs/development.md | 1 + tools/ReleaseTools.psm1 | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/development.md b/docs/development.md index c75eda1616..72d86ce132 100644 --- a/docs/development.md +++ b/docs/development.md @@ -80,6 +80,7 @@ New-DraftRelease -RepositoryName vscode-powershell # Upload PowerShellEditorServices.zip (for other extensions) # Upload VSIX and Install-VSCode.ps1 # Publish draft releases and merge (don't squash!) branches +# Check telemetry for stability before releasing vsce publish --packagePath ./PowerShell-.vsix # Update Install-VSCode.ps1 on gallery Publish-Script -Path ./Install-VSCode.ps1 -NuGetApiKey (Get-Secret "PowerShell Gallery API Key" -AsPlainText) diff --git a/tools/ReleaseTools.psm1 b/tools/ReleaseTools.psm1 index dd3f56ba3c..77d2d585f7 100644 --- a/tools/ReleaseTools.psm1 +++ b/tools/ReleaseTools.psm1 @@ -238,7 +238,7 @@ function Update-Changelog { if ($PSCmdlet.ShouldProcess("$RepositoryName/$ChangelogFile", "git")) { Update-Branch -Version $Version git add $ChangelogFile - git commit -m "Update CHANGELOG for $Version" + git commit -m "Update CHANGELOG for ``v$Version``" } Pop-Location @@ -324,7 +324,7 @@ function Update-Version { if ($PSCmdlet.ShouldProcess("$RepositoryName/v$Version", "git commit")) { Update-Branch -Version $Version - git commit -m "Bump version to v$Version" + git commit -m "Bump version to ``v$Version``" } Pop-Location @@ -350,6 +350,7 @@ function New-DraftRelease { $ReleaseParams = @{ Draft = $true Tag = "v$Version" + Committish = "release/v$Version" Name = "v$Version" Body = $ChangeLog PreRelease = [bool]$Version.PreReleaseLabel From ba7ce2dcf5e3476e7cd671ca15a30dd7b63dc6bc Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 23 Jun 2021 09:24:29 -0700 Subject: [PATCH 3/6] Don't create tag locally --- tools/ReleaseTools.psm1 | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/tools/ReleaseTools.psm1 b/tools/ReleaseTools.psm1 index 77d2d585f7..217e313da6 100644 --- a/tools/ReleaseTools.psm1 +++ b/tools/ReleaseTools.psm1 @@ -339,7 +339,6 @@ function Update-Version { are prefixed with a `v`. Creates a Git tag if it does not already exist. #> function New-DraftRelease { - [CmdletBinding(SupportsShouldProcess)] param( [Parameter(Mandatory)] [ValidateSet([RepoNames])] @@ -349,23 +348,12 @@ function New-DraftRelease { $Changelog = (Get-FirstChangelog -RepositoryName $RepositoryName) -join "`n" $ReleaseParams = @{ Draft = $true + # NOTE: We rely on GitHub to create the tag at that branch. Tag = "v$Version" Committish = "release/v$Version" Name = "v$Version" Body = $ChangeLog PreRelease = [bool]$Version.PreReleaseLabel - # TODO: Pass -WhatIf and -Confirm parameters correctly. - } - - if ($PSCmdlet.ShouldProcess("$RepositoryName/v$Version", "git tag")) { - # NOTE: This a side effect neccesary for Git operations to work. - Push-Location -Path "$PSScriptRoot/../../$RepositoryName" - if (-not (git show-ref --tags "v$Version")) { - git tag "v$Version" - } else { - Write-Warning "git tag $RepositoryName/v$Version already exists!" - } - Pop-Location } Get-GitHubRepository -OwnerName PowerShell -RepositoryName $RepositoryName | From d0ae1f13b266ed37c8db6e258a83095790873aa2 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 23 Jun 2021 09:26:53 -0700 Subject: [PATCH 4/6] Sign `InvokePesterStub.ps1` --- .vsts-ci/templates/release-general.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.vsts-ci/templates/release-general.yml b/.vsts-ci/templates/release-general.yml index 2d1261eb41..5ab6752f3f 100644 --- a/.vsts-ci/templates/release-general.yml +++ b/.vsts-ci/templates/release-general.yml @@ -33,16 +33,16 @@ steps: - template: EsrpSign.yml@ComplianceRepo parameters: - # TODO: $[in(variables['Build.Reason'], 'Manual', 'ResourceTrigger')] - shouldSign: true buildOutputPath: '$(Build.ArtifactStagingDirectory)/vscode-powershell' signOutputPath: '$(Build.ArtifactStagingDirectory)/Signed' alwaysCopy: true # So publishing works certificateId: 'CP-230012' # Authenticode certificate useMinimatch: true # This enables the use of globbing + shouldSign: true # We always want to sign # NOTE: Code AKA *.vsix files are not signed pattern: | Install-VSCode.ps1 + InvokePesterStub.ps1 - template: EsrpScan.yml@ComplianceRepo parameters: From a656311c898ebe093ae4caf16e6518368c81251d Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 23 Jun 2021 11:38:33 -0700 Subject: [PATCH 5/6] Document our versioning scheme --- docs/development.md | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/development.md b/docs/development.md index 72d86ce132..4ded0677e1 100644 --- a/docs/development.md +++ b/docs/development.md @@ -86,6 +86,54 @@ vsce publish --packagePath ./PowerShell-.vsix Publish-Script -Path ./Install-VSCode.ps1 -NuGetApiKey (Get-Secret "PowerShell Gallery API Key" -AsPlainText) ``` +### Versioning + +For both our repositories we use Git tags in the form `vX.Y.Z` to mark the +releases in the codebase. We use the GitHub Release feature to create these +tags. Branches are used in the process of creating a release, e.g. +`release/vX.Y.Z`, but are deleted after the release is completed (and merged +into `master`). + +For PowerShellEditor Services, we simply follow semantic versioning, e.g. +`vX.Y.Z`. We do not release previews frequently because this dependency is not +generally used directly: it's a library consumed by other projects which +themselves use preview releases for beta testing. + +For the VS Code PowerShell Extension, our version follows `vYYYY.MM.X`, that is: +current year, current month, and patch version (not day). This is not semantic +versioning because of issues with how the VS Code marketplace and extension +hosting API itself uses our version number. This scheme _does not_ mean we +release on a chronological schedule: we release based on completed work. If the +month has changed over since the last release, the patch version resets to 0. +Each subsequent release that month increments the patch version. + +Before releasing a "stable" release we should almost always first release a +"preview" of the same code. The exception to this is "hotfix" releases where we +need to push _only_ bug fixes out as soon as possible, and these should be built +off the last release's codebase (found from the Git tag). The preview release is +uploaded separately to the marketplace as the "PowerShell Preview" extension. It +should not significantly diverge from the stable release ("PowerShell" +extension), but is used for public beta testing. The preview version should +match the upcoming stable version, but with `-preview` appended. When multiple +previews are needed, the patch version is incremented, and the last preview's +version is used for the stable release. (So the stable version may jump a few +patch versions in between releases.) + +For example, the date is May 7, 2022. The last release was in April, and its +version was `v2022.4.3`. Some significant work has been completed and we want to +release the extension. First we create a preview release with version +`v2022.5.0-preview` (the patch reset to 0 because the month changed, and +`-preview` was appended). After publishing, some issues were identified and we +decided we needed a second preview release. Its version is `v2022.5.1-preview`. +User feedback indicates that preview is working well, so to create a stable +release we use the same code (but with an updated changelog etc.) and use +version `v2022.5.1`, the _first_ stable release for May (as `v2022.5.0` was +skipped due to those identified issues in the preview). All of these releases +may consume the same or different version of PowerShell Editor Services, say +`v3.2.4`. It may update between preview versions or stable versions (but should +not change between a preview and its associated stable release, as they should +use the same code which includes dependencies). + ### Pending Improvements * `Update-Changelog` should verify the version is in the correct format From f45823b5ed0bfe51ac3e9f7f2d67087c2364c996 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Tue, 22 Jun 2021 18:27:16 -0700 Subject: [PATCH 6/6] Upload assets to release --- docs/development.md | 1 - tools/ReleaseTools.psm1 | 11 ++++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/development.md b/docs/development.md index 4ded0677e1..4dbdf37a94 100644 --- a/docs/development.md +++ b/docs/development.md @@ -140,6 +140,5 @@ use the same code which includes dependencies). * `Update-Changelog` could be faster by not downloading _every_ PR * `Update-Changelog` should use exactly two emoji and in the right order * `Update-Version` could be run by `Update-Changelog` -* `New-DraftRelease` could automatically set the tag pointers and upload the binaries * The build should emit an appropriately named VSIX instead of us manually renaming it * A `Publish-Binaries` function could be written to push the binaries out diff --git a/tools/ReleaseTools.psm1 b/tools/ReleaseTools.psm1 index 217e313da6..d4e82f51ad 100644 --- a/tools/ReleaseTools.psm1 +++ b/tools/ReleaseTools.psm1 @@ -342,7 +342,10 @@ function New-DraftRelease { param( [Parameter(Mandatory)] [ValidateSet([RepoNames])] - [string]$RepositoryName + [string]$RepositoryName, + + [Parameter(ValueFromPipeline)] + [string[]]$Assets ) $Version = Get-Version -RepositoryName $RepositoryName $Changelog = (Get-FirstChangelog -RepositoryName $RepositoryName) -join "`n" @@ -354,8 +357,10 @@ function New-DraftRelease { Name = "v$Version" Body = $ChangeLog PreRelease = [bool]$Version.PreReleaseLabel + OwnerName = "PowerShell" + RepositoryName = $RepositoryName } - Get-GitHubRepository -OwnerName PowerShell -RepositoryName $RepositoryName | - New-GitHubRelease @ReleaseParams + $Release = New-GitHubRelease @ReleaseParams + $Assets | New-GitHubReleaseAsset -Release $Release.Id }