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: diff --git a/docs/development.md b/docs/development.md index c75eda1616..4dbdf37a94 100644 --- a/docs/development.md +++ b/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-.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 diff --git a/tools/ReleaseTools.psm1 b/tools/ReleaseTools.psm1 index f65dfbeca1..d4e82f51ad 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,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 }