Release refinements

.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:

docs/development.md

@@ -80,17 +80,65 @@ 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-<version>.vsix
 # Update Install-VSCode.ps1 on gallery
 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
 * `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

tools/ReleaseTools.psm1

@@ -134,6 +134,21 @@ function Get-FirstChangelog {
     )
 }
 
+<#
+.SYNOPSIS
+  Creates and checks out `release/v<version>` 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,12 +236,9 @@ 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"
+        git commit -m "Update CHANGELOG for ``v$Version``"
     }
 
     Pop-Location
@@ -311,7 +323,8 @@ function Update-Version {
     }
 
     if ($PSCmdlet.ShouldProcess("$RepositoryName/v$Version", "git commit")) {
-        git commit -m "Bump version to v$Version"
+        Update-Branch -Version $Version
+        git commit -m "Bump version to ``v$Version``"
     }
 
     Pop-Location
@@ -326,34 +339,28 @@ 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])]
-        [string]$RepositoryName
+        [string]$RepositoryName,
+
+        [Parameter(ValueFromPipeline)]
+        [string[]]$Assets
     )
     $Version = Get-Version -RepositoryName $RepositoryName
     $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
+        OwnerName  = "PowerShell"
+        RepositoryName = $RepositoryName
     }
 
-    Get-GitHubRepository -OwnerName PowerShell -RepositoryName $RepositoryName |
-        New-GitHubRelease @ReleaseParams
+    $Release = New-GitHubRelease @ReleaseParams
+    $Assets | New-GitHubReleaseAsset -Release $Release.Id
 }