From 5ae237d9a474bd8e80b4f7bf173d148fa7d1e9ae Mon Sep 17 00:00:00 2001 From: Andy Jordan Date: Wed, 12 Jul 2023 18:16:30 -0700 Subject: [PATCH] Update readme Fixed issues with badges, removed Gitter (not actively monitored by us so let's prefer advertising Discord), lots of updates and reorganizing, more useful links (like to the official guide), removed confusing or not useful information (such as how to install from the script or open the examples, neither of which we actively keep updated), and sorry Patrick but after changing my name now alphabetically it's first. --- README.md | 183 ++++++++++++++++++++++++------------------------------ 1 file changed, 81 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 5dbe1ad62b..460891ba6d 100644 --- a/README.md +++ b/README.md @@ -1,142 +1,121 @@ # PowerShell for Visual Studio Code [![Build Status](https://dev.azure.com/powershell/vscode-powershell/_apis/build/status/PowerShell.vscode-powershell?branchName=main)](https://dev.azure.com/powershell/vscode-powershell/_build/latest?definitionId=51&branchName=main) -[![Version](https://vsmarketplacebadges.dev/version-short/ms-vscode.powershell.svg)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) -[![Installs](https://vsmarketplacebadges.dev/installs-short/ms-vscode.powershell.svg)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) +[![Version](https://img.shields.io/visual-studio-marketplace/v/ms-vscode.PowerShell)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) +[![Installs](https://img.shields.io/visual-studio-marketplace/i/ms-vscode.PowerShell)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) [![Join the chat on Discord](https://img.shields.io/discord/180528040881815552.svg?label=%23vscode&logo=discord&logoColor=white)](https://aka.ms/powershell-vscode-discord) -[![Join the chat on Gitter](https://badges.gitter.im/PowerShell/vscode-powershell.svg)](https://gitter.im/PowerShell/vscode-powershell?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -This extension provides rich PowerShell language support for [Visual Studio Code](https://github.com/Microsoft/vscode) (VS Code). +This extension provides rich [PowerShell][] language support for [Visual Studio Code][] (VS Code). Now you can write and debug PowerShell scripts using the excellent IDE-like interface that VS Code provides. -This extension is powered by the PowerShell language server, -[PowerShell Editor Services](https://github.com/PowerShell/PowerShellEditorServices). -This leverages the -[Language Server Protocol](https://microsoft.github.io/language-server-protocol/) -where `PowerShellEditorServices` is the server and `vscode-powershell` is the client. - -Also included in this extension is the PowerShell ISE theme for Visual Studio Code. It is -not activated by default, but after installing this extension either click "Set Color -Theme" or use the [theme picker](https://code.visualstudio.com/docs/getstarted/themes) and -select "PowerShell ISE" for a fun and familiar experience. +This repository, `vscode-powershell`, is the [Language Server Protocol][] client for VS +Code and [`PowerShellEditorServices`][] is the server (also used by other editors, such as +Emacs and Vim). + +[PowerShell]: https://github.com/PowerShell/PowerShell +[Visual Studio Code]: https://github.com/Microsoft/vscode +[`PowerShellEditorServices`]: https://github.com/PowerShell/PowerShellEditorServices +[Language Server Protocol]: https://microsoft.github.io/language-server-protocol/ + +## Available Features + +- [Syntax highlighting][] +- Advanced built-in [code snippets][] +- [IntelliSense][] for cmdlets and more +- [Problems][] reported by [PowerShell Script Analyzer][] +- [Go to Definition][] of cmdlets, variables, classes and more +- [Find References][] of cmdlets, variables, classes and more +- Document and Workspace [Symbol Navigation][] +- Symbol-based [Outline View][] +- Run selected PowerShell code in current terminal using F8 +- Launch online help for the symbol under the cursor using Ctrl+F1 +- PowerShell [Debugger][] integration +- An Extension Terminal that can interact with the debugger (try `Set-PSBreakpoint`!) +- PowerShell ISE theme findable in the [theme picker][] +- Also try ISE Mode with the **Toggle ISE Mode** command + +Bundled with the extension is the PowerShell ISE theme. It is not activated by default, +but after installing this extension either click **Set Color Theme** or use the [theme +picker][] and select **PowerShell ISE**. + +[Syntax highlighting]: https://github.com/PowerShell/EditorSyntax +[code snippets]: https://code.visualstudio.com/docs/editor/userdefinedsnippets +[IntelliSense]: https://code.visualstudio.com/docs/editor/intellisense +[Problems]: https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_errors-and-warnings +[PowerShell Script Analyzer]: http://github.com/PowerShell/PSScriptAnalyzer +[Go to Definition]: https://code.visualstudio.com/docs/editor/editingevolved#_go-to-definition +[Find References]: https://code.visualstudio.com/docs/editor/editingevolved#_reference-information +[Symbol Navigation]: https://code.visualstudio.com/docs/editor/editingevolved#_open-symbol-by-name +[Outline View]: https://code.visualstudio.com/docs/getstarted/userinterface#_outline-view +[Debugger]: https://learn.microsoft.com/powershell/scripting/dev-cross-plat/vscode/using-vscode#debugging-with-visual-studio-code +[theme picker]: https://code.visualstudio.com/docs/getstarted/themes ## Platform Support -The extension _should_ work anywhere VS Code itself and PowerShell Core 7.2 or higher is -[supported][]. For Windows PowerShell, only version 5.1 is supported. Please note that -PowerShell Core 6, 7.0, and 7.1 have reached end-of-support. Our test matrix includes the -following: - -- **Windows Server 2022** with Windows PowerShell 5.1 and PowerShell Core 7.2.11 -- **Windows Server 2019** with Windows PowerShell 5.1 and PowerShell Core 7.2.11 -- **macOS 11** with PowerShell Core 7.2.11 -- **Ubuntu 20.04** with PowerShell Core 7.2.11 +The extension should work anywhere VS Code itself and PowerShell Core 7.2 or higher is +[supported][]. For Windows PowerShell, only version 5.1 is supported and only on a best-effort +basis. PowerShell Core 6, 7.0, and 7.1 have reached end-of-support. We test the following +configurations: -[supported]: https://docs.microsoft.com/en-us/powershell/scripting/powershell-support-lifecycle +- **Windows Server 2022** with Windows PowerShell 5.1 and PowerShell Core 7.2 +- **Windows Server 2019** with Windows PowerShell 5.1 and PowerShell Core 7.2 +- **macOS 11** with PowerShell Core 7.2 +- **Ubuntu 20.04** with PowerShell Core 7.2 -Read the [installation instructions](https://docs.microsoft.com/en-us/powershell/scripting/components/vscode/using-vscode) +Read the [installation instructions][] to get more details on how to use the extension on these platforms. For Windows PowerShell 5.1, [.NET Framework 4.8][dotnet-framework] or higher is required. +[supported]: https://docs.microsoft.com/en-us/powershell/scripting/powershell-support-lifecycle +[installation instructions]: https://docs.microsoft.com/en-us/powershell/scripting/components/vscode/using-vscode [dotnet-framework]: https://dotnet.microsoft.com/en-us/download/dotnet-framework -**Read the [troubleshooting guide](./docs/troubleshooting.md) for answers to common questions.** - -## Features - -- Syntax highlighting -- Code snippets -- IntelliSense for cmdlets and more -- Rule-based analysis provided by [PowerShell Script Analyzer](http://github.com/PowerShell/PSScriptAnalyzer) -- Go to Definition of cmdlets and variables -- Find References of cmdlets and variables -- Document and workspace symbol discovery -- Run selected selection of PowerShell code using F8 -- Launch online help for the symbol under the cursor using Ctrl+F1 -- Local script debugging -- Extension Terminal support -- PowerShell ISE color theme - ## Installing the Extension -You can install the official release of the PowerShell extension by following the steps -in the [Visual Studio Code documentation](https://code.visualstudio.com/docs/editor/extension-gallery). -In the Extensions pane, search for "PowerShell" extension and install it there. You will -get notified automatically about any future extension updates! +The PowerShell extension can be installed from the Visual Studio Code Marketplace by +clicking the [**Install Button**][]. You can also install the PowerShell extension from +within VS Code by opening the **Extensions** view with keyboard shortcut +Ctrl+Shift+X, typing PowerShell, and selecting the extension. -You can also install a VSIX package from our [releases page](https://github.com/PowerShell/vscode-powershell/releases) by following the -[Install from a VSIX](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix) -instructions. The easiest way is through the command line: +We would encourage you to try the _pre-release_ version whenever possible. When a +_Pre-Release_ is available, it can be installed from the marketplace using the +**Switch to Pre-Release Version** button. You can switch back to the stable version of the +extension by using the **Switch to Release Version** button that will appear. You can also +downgrade to other versions of the extension using the arrow next to the **Uninstall** +button and choosing **Install Another Version**. -```powershell -code --install-extension powershell-.vsix -``` +[**Install Button**]: vscode:extension/ms-vscode.PowerShell -> NOTE: If you are using VS Code Insiders, the command will be `code-insiders`. +## Getting Help -### Script-based Installation +If you experience any problems with the PowerShell Extension, see the +[troubleshooting docs](docs/troubleshooting.md) for common issues. -If you're on Windows 7 or greater with the [PowerShellGet](https://msdn.microsoft.com/powershell/gallery/readme) -module installed, you can easily install both Visual Studio Code and the PowerShell -extension by running the following command: +If you find a bug, please [open an issue][] so we can fix it. -```powershell -Install-Script Install-VSCode -Scope CurrentUser; Install-VSCode.ps1 -``` +Don't forget to check out the official guide on +[Using VS Code for PowerShell Development][]. -You will need to accept the prompts that appear if this is your first time running -the `Install-Script` command. +[Using VS Code for PowerShell Development]: https://learn.microsoft.com/en-us/powershell/scripting/dev-cross-plat/vscode/using-vscode +[open an issue]: https://github.com/PowerShell/vscode-powershell/issues/new/choose -**Alternatively** you can download and execute the script directly from the web -without the use of `Install-Script`. However we **highly recommend** that you -[read the script](https://raw.githubusercontent.com/PowerShell/vscode-powershell/main/scripts/Install-VSCode.ps1) -first before running it in this way! - -```powershell -iex (iwr https://raw.githubusercontent.com/PowerShell/vscode-powershell/main/scripts/Install-VSCode.ps1) -``` - -## Reporting Problems +## Contributing to the Code -If you experience any problems with the PowerShell Extension, see -[the troubleshooting docs](./docs/troubleshooting.md) for information -on diagnosing and reporting issues. +Check out the [development documentation](docs/development.md) for more details +on how to contribute to this extension! ## Security Note For any security issues, please see [here](./SECURITY.md). -## Example Scripts - -There are some example scripts in the extension's `examples` folder that you can -use to discover PowerShell editing and debugging functionality. Please -check out the included [README.md](examples/README.md) file to learn more about -how to use them. - -This folder can be found at the following path: - -```powershell -$HOME/.vscode[-insiders]/extensions/ms-vscode.powershell[-preview]-/examples -``` - -To open/view the extension's examples in Visual Studio Code, run the following from your -PowerShell session: - -```powershell -code (Get-ChildItem $HOME/.vscode/extensions/ms-vscode.powershell-*/examples)[-1] -``` - -## Contributing to the Code - -Check out the [development documentation](docs/development.md) for more details -on how to contribute to this extension! - ## Maintainers -- Patrick Meinecke - [@SeeminglyScience](https://github.com/SeeminglyScience) +### Current + - Andy Jordan - [@andschwa](https://github.com/andschwa) +- Patrick Meinecke - [@SeeminglyScience](https://github.com/SeeminglyScience) - Sydney Smith - [@SydneyhSmith](https://github.com/SydneyhSmith) ### Emeriti @@ -148,7 +127,7 @@ on how to contribute to this extension! ## License -This extension is [licensed under the MIT License](LICENSE.txt). Please see the +This extension is [licensed under the MIT License](LICENSE.txt). Please see the [third-party notices](Third%20Party%20Notices.txt) file for details on the third-party binaries that we include with releases of this project.