Development Instructions for the PowerShell Extension
You'll need to clone two repositories and set up your development environment to before you can proceed.
vscode-powershellfolder and the
PowerShellEditorServicesfolder should be next to each other on the file system. Code in
vscode-powershelllooks for PSES at
../PowerShellEditorServicesif you're building locally so PSES must be in that location.
Follow the development instructions for PowerShell Editor Services. You will need to complete this step before proceeding.
Install the latest Visual Studio Code Insiders release
You can also use the standard Visual Studio Code release. Both will work, but using VSCode Insiders means the extension can be developed ready for new features and changes in the next VSCode release.
Install Node.js 10.x or higher.
Building the Code
From Visual Studio Code
Press Ctrl+P and type
From a PowerShell prompt
As a developer, you may want to use
Invoke-Build LinkEditorServices to setup a symbolic
link to its modules instead of copying the files. This will mean the built extension will
always have the latest version of your PowerShell Editor Services build, but this cannot
be used to package the extension into a VSIX. So it is a manual step.
Launching the extension
From Visual Studio Code
To debug the extension, press F5. To run the extension without debugging, press Ctrl+F5 or Cmd+F5 on macOS.
From a command prompt
code --extensionDevelopmentPath="c:\path\to\vscode-powershell" .
For more information on contributing snippets please read our snippet requirements.
Creating a Release
These are the current steps for creating a release for both the editor services and the extension. ADO access is restricted to Microsoft employees and is used to sign and validate the produced binaries before publishing on behalf of Microsoft. The comments are manual steps.
Import-Module ./tools/ReleaseTools.psm1 New-Release -PsesVersion <version> -VsceVersion <version> # Amend changelog as necessary # Push release branches to ADO # Permit both pipelines to draft GitHub releases # Download and test assets # Check telemetry for stability before releasing # Publish draft releases and merge (don't squash!) branches # Permit vscode-extension pipeline to publish to marketplace
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. The ephemeral branch
release is used in the process of creating a release for each repository, primarily for
the Pull Requests and for Azure DevOps triggers. Once the release PRs are merged, the
branch is deleted until used again to prepare the next release. This branch does not
mark any specific release, that is the point of the tags.
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.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" 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
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
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
v2022.5.1, the first stable release for May (as
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).
Update-Changelogshould verify the version is in the correct format
Update-Changelogcould be faster by not downloading every PR