Document our versioning scheme

Author: andyleejordan

docs/development.md

@@ -86,6 +86,54 @@ vsce publish --packagePath ./PowerShell-<version>.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