Update version tools and docs for new version scheme

Author: andyleejordan

docs/development.md

@@ -74,14 +74,14 @@ New-ReleaseBundle -PsesVersion <version> -VsceVersion <version>
 # Permit vscode-extension pipeline to publish to marketplace
 ```
 
-If rolling from pre-release to stable, use:
+If rolling from pre-release to release, use:
 
 ```powershell
 New-Release -RepositoryName vscode-powershell -Version <version>
 ```
 
 This is because we do not change the version of PowerShell Editor Services between a
-pre-release and the subsequent stable release, so we only need to release the extension.
+pre-release and the subsequent release, so we only need to release the extension.
 
 ### Versioning
 
@@ -97,48 +97,54 @@ For PowerShellEditor Services, we simply follow semantic versioning, e.g.
 generally used directly: it's a library consumed by other projects which
 themselves use pre-releases for beta testing.
 
-For the VS Code PowerShell Extension, our version follows `vYYYY.M.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 version we should almost always first release a preview of the
-same code, which is a _pre-release_. 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 pre-release is uploaded to the
-marketplace using the `--pre-release` flag given to `vsce` (the CLI tool used to do so).
-The previous separate "PowerShell Preview" extension has been deprecated in favor of using
-the marketplace's support for [pre-releases][] on the stable and now one-and-only
+For the VS Code PowerShell Extension, our version follows `vYYYY.X.Z`, that is: current
+year, minor version, and patch version. This is not semantic versioning because of issues
+with how the VS Code marketplace and extension hosting API itself uses our version number.
+We do not release on a chronological schedule: we release based on completed work. For
+historical reasons we are stuck with the major version being year.
+
+Before releasing a stable version (a _release_) we should almost always first release a
+preview of the same code, which is a _pre-release_. 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 pre-release is
+uploaded to the marketplace using the `--pre-release` flag given to `vsce` (the CLI tool
+used to do so). The previous separate "PowerShell Preview" extension has been deprecated
+in favor of using the marketplace's support for [pre-releases][] on the one-and-only
 extension.
 
 Because the marketplace does not actually understand Semantic Versioning pre-release tags
 (the `-preview` suffix), the patch numbers need to increment continuously, but we append
 `-preview` to _our_ version in the changelog and Git tags. When multiple pre-releases are
 needed, the patch version is incremented (again because the marketplace ignores the
-pre-release tag, we can't do `-alpha`, `-beta` etc.). Since migrating to a single
-extension, the stable release has to increment one more after the last pre-release. So the
-stable version may jump a few patch versions in between releases. Furthermore, the
-`preview` field in the extension's manifest (the `package.json` file) is _always_ `false`,
-even for pre-releases, because the marketplace takes the information from the latest
-release inclusive of pre-releases, hence it was causing the one-and-only extension to look
-like it was in preview. This is also why the icon no longer changes to the PowerShell
-Preview icon for pre-releases. When they support pre-releases better (ideally that means
-supporting the pre-release tags in full) we can revisit this.
+pre-release tag, we can't do `-alpha`, `-beta` etc.). The `preview` field in
+the extension's manifest (the `package.json` file) is _always_ `false`, even for
+pre-releases, because the marketplace takes the information from the latest release
+inclusive of pre-releases, hence it was causing the one-and-only extension to look like it
+was in preview. This is also why the icon no longer changes to the PowerShell Preview icon
+for pre-releases. When they support pre-releases better (ideally that means supporting the
+pre-release tags in full) we can revisit this.
+
+Furthermore, for releases, the minor version must be _even_ (like 0, 2, etc.) and for
+pre-releases it must be _odd_ (like 1, 3, etc.), and an upcoming release's version must be
+`n-1` of the pre-release which previews it. That is, release `v2024.0.0` is previewed in
+the pre-release `v2024.1.0`. This scheme is designed such that the "newest" (by version)
+release is always a pre-release, so that the VS Code marketplace _always_ shows a
+pre-release option. When we previously did this the other way around (incrementing the
+release as `n+1` to the pre-release), every time we released, the pre-release option
+(dropdown) in the marketplace would unfortunately disappear.
 
 [pre-releases]: https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions
 
-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 pre-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 pre-release. Its version is
-`v2022.5.1-preview`. User feedback indicates that pre-release 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.2`, the _first_ stable release for May (as `v2022.5.0` was skipped due to
-those identified issues in the pre-release). All of these releases may consume the same or
-different version of PowerShell Editor Services, say `v3.2.4`. It may update between
-pre-release versions or stable versions, but must not change between a pre-release and the
-subsequent stable release, as they should use the same code which includes dependencies.
+For example, the date is August 23, 2023. The last release was in June, and its version
+was `v2023.6.0`. Some significant work has been completed and we want to release the
+extension, so the next release will be `v2023.8.0` (the minor version is `n+2` because it
+must remain even, it only coincidentally matches the month). That means first we create a
+pre-release with version `v2023.9.0-preview` (the minor version is `n+1` of the upcoming
+release, and `-preview` was appended). After publishing, some issues were identified and
+we decided we needed a second pre-release. Its version is `v2023.9.1-preview`. User
+feedback hopefully indicates that the pre-release is working well, so to create a release
+we will use the same code (but with an updated changelog etc.) and use version
+`v2023.8.0`, the _next_ release since `v2023.6.0`. The version of PowerShell Editor
+Services may update between pre-releases or releases, but must not change between a
+pre-release and its subsequent release, as they should use the same code (which includes
+dependencies).

tools/ReleaseTools.psm1

@@ -44,7 +44,7 @@ function Get-Bullets {
     )
     begin {
         $SkipThanks = @(
-            'andschwa'
+            'andyleejordan'
             'daxian-dbw'
             'PaulHigin'
             'SeeminglyScience'

tools/VersionTools.psm1

@@ -125,13 +125,17 @@ function Test-VersionIsValid {
             if ($SemanticVersion.Major -ne $Date.Year) {
                 throw "Major version should be the current year!"
             }
-            if ($SemanticVersion.Minor -ne $Date.Month) {
-                throw "Minor version should be the current month!"
-            }
             if ($SemanticVersion.PreReleaseLabel) {
                 if ($SemanticVersion.PreReleaseLabel -ne "preview") {
                     throw "Suffix should only be 'preview'!"
                 }
+                if ($SemanticVersion.Minor % 2 -eq 0) {
+                    throw "Minor version must be odd for pre-release!"
+                }
+            } else {
+                if ($SemanticVersion.Minor % 2 -ne 0) {
+                    throw "Minor version must be even for pre-release!"
+                }
             }
         }
         "PowerShellEditorServices" {