From 745e47298ac7e25c4ca0ac76732bdb26106a9201 Mon Sep 17 00:00:00 2001 From: Robert Holt Date: Thu, 20 Sep 2018 14:43:47 -0700 Subject: [PATCH 01/10] Update and restructure README.md --- README.md | 78 +++++++++++++++++++++++++++---------------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index e4e273c129..272ea7cf75 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ that Visual Studio Code provides. ## Platform support -- **Windows 7 through 10** with PowerShell v3 and higher -- **Linux** with PowerShell v6 (all PowerShell-supported distributions) -- **macOS and OS X** with PowerShell v6 +- **Windows 7 through 10** with Windows PowerShell v3 and higher, and PowerShell Core +- **Linux** with PowerShell Core (all PowerShell-supported distributions) +- **macOS and OS X** with PowerShell Core Read the [installation instructions](https://github.com/PowerShell/PowerShell/blob/master/docs/learning-powershell/using-vscode.md) to get more details on how to use the extension on these platforms. @@ -26,32 +26,10 @@ Read the [FAQ](https://github.com/PowerShell/vscode-powershell/wiki/FAQ) for ans - 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` +- Run selected selection of PowerShell code using F8 +- Launch online help for the symbol under the cursor using Ctrl+F1 - Local script debugging and basic interactive console support! -## Quick Installation - -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: - -```powershell -Install-Script Install-VSCode -Scope CurrentUser; Install-VSCode.ps1 -``` - -You will need to accept the prompts that appear if this is your first time running -the `Install-Script` command. - -**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://github.com/PowerShell/vscode-powershell/blob/develop/scripts/Install-VSCode.ps1) -first before running it in this way! - -```powershell -iex (iwr https://git.io/vbxjj) -``` - ## Installing the Extension You can install the official release of the PowerShell extension by following the steps @@ -69,23 +47,26 @@ code --install-extension PowerShell-.vsix > NOTE: If you are using VS Code Insiders, the command will be `code-insiders`. -## 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. +## Script-based Installation -This folder can be found at the following path: +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: -``` -C:\Users\\.vscode\extensions\ms-vscode.PowerShell-\examples +```powershell +Install-Script Install-VSCode -Scope CurrentUser; Install-VSCode.ps1 ``` -To open/view the extension's examples in Visual Studio Code, run the following from your PowerShell command prompt: +You will need to accept the prompts that appear if this is your first time running +the `Install-Script` command. + +**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://github.com/PowerShell/vscode-powershell/blob/develop/scripts/Install-VSCode.ps1) +first before running it in this way! ```powershell -code (Get-ChildItem $Home\.vscode\extensions\ms-vscode.PowerShell-*\examples)[-1] +iex (iwr https://git.io/vbxjj) ``` ## Reporting Problems @@ -130,6 +111,25 @@ You have two options for sending us the logs: 2. If you are editing scripts that don't contain sensitive information, you can drag and drop your logs ZIP file into the GitHub issue that you are creating. +## 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: + +``` +C:\Users\\.vscode\extensions\ms-vscode.PowerShell-\examples +``` + +To open/view the extension's examples in Visual Studio Code, run the following from your PowerShell command prompt: + +```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 @@ -139,7 +139,7 @@ on how to contribute to this extension! - [Keith Hill](https://github.com/rkeithhill) - [@r_keith_hill](http://twitter.com/r_keith_hill) - [Tyler Leonhardt](https://github.com/tylerl0706) - [@TylerLeonhardt](http://twitter.com/tylerleonhardt) -- [David Wilson](https://github.com/daviwil) - [@daviwil](http://twitter.com/daviwil) +- [Rob Holt](https://github.com/rjmholt) ## License From fa90146469829a25ca79c1078519d7cee2a11322 Mon Sep 17 00:00:00 2001 From: Robert Holt Date: Thu, 20 Sep 2018 16:33:30 -0700 Subject: [PATCH 02/10] Update troubleshooting.md --- docs/development.md | 19 ++-- docs/troubleshooting.md | 192 +++++++++++++++++++++++----------------- 2 files changed, 122 insertions(+), 89 deletions(-) diff --git a/docs/development.md b/docs/development.md index 37f374dbf3..8a9c32b142 100644 --- a/docs/development.md +++ b/docs/development.md @@ -5,25 +5,28 @@ You'll need to clone two repositories and set up your development environment to before you can proceed. -### 1. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [vscode-powershell repository](https://github.com/PowerShell/vscode-powershell) +1. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [vscode-powershell repository](https://github.com/PowerShell/vscode-powershell) -### 2. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [PowerShell Editor Services repository](https://github.com/PowerShell/PowerShellEditorServices) +2. [Fork and clone](https://help.github.com/articles/fork-a-repo/) the [PowerShell Editor Services repository](https://github.com/PowerShell/PowerShellEditorServices) -### 3. Follow the [development instructions](https://github.com/PowerShell/PowerShellEditorServices#development) for PowerShell Editor Services +3. Follow the [development instructions](https://github.com/PowerShell/PowerShellEditorServices#development) for PowerShell Editor Services. **You will need to complete this step before proceeding**. -### 4. Install [Visual Studio Code Insiders Release](https://code.visualstudio.com/insiders) +4. Install the latest [Visual Studio Code Insiders release](https://code.visualstudio.com/insiders) + - You can also use the [standard Visual Studio Code release](https://code.visualstudio.com/). Both will work, but using VSCode + Insiders means the extension can be developed ready for new features + and changes in the next VSCode release. -### 5. Install [Node.js](https://nodejs.org/en/) 6.0.0 or higher. +5. Install [Node.js](https://nodejs.org/en/) 6.0.0 or higher. ## Building the Code #### From Visual Studio Code: -Press Ctrl+P and type `task build` +Press Ctrl+P and type `task build` This will compile the TypeScript files in the project to JavaScript files. -#### From a command prompt: +#### From a PowerShell prompt: ``` Invoke-Build Build @@ -34,7 +37,7 @@ Invoke-Build Build #### From Visual Studio Code: To debug the extension, press F5. To run the extension without debugging, -press Ctrl+F5 or Cmd+F5 on macOS. +press Ctrl+F5 or Cmd+F5 on macOS. #### From a command prompt: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b7fb7e8dd8..0ca31cacea 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,84 +1,114 @@ # Troubleshooting PowerShell Extension Issues This document contains troubleshooting steps for commonly reported issues when using the -PowerShell extension for Visual Studio Code. - -## Windows - -### 1. IntelliSense is extremely slow on PowerShell 5.0 - -There is a known issue with PowerShell 5.0 which, for a small number of users, causes IntelliSense -(code completions) to return after 5-15 seconds. The following steps *might* resolve the issue for you: - -1. In a PowerShell console, run the following command: `Remove-Item -Force -Recurse $env:LOCALAPPDATA\Microsoft\Windows\PowerShell\CommandAnalysis` -2. Restart Visual Studio Code and try getting IntelliSense again. - -This issue has been resolved in PowerShell 5.1. - -## macOS (OS X) - -### 1. PowerShell IntelliSense does not work, can't debug scripts - -The most common problem when the PowerShell extension doesn't work on macOS is that you have -an alpha version of PowerShell installed. To upgrade to the latest beta, please follow the -[Install Instructions](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#macos-1012). - -If you'd prefer to use an alpha version of PowerShell, then OpenSSL must be installed. -You can check for the installation of OpenSSL by looking for the following files: - -If installed using Homebrew: - -``` -/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib -/usr/local/opt/openssl/lib/libssl.1.0.0.dylib -``` - -If installed by some other means: - -``` -/usr/local/lib/libcrypto.1.0.0.dylib -/usr/local/lib/libssl.1.0.0.dylib -``` - -The extension should check for these files and direct you to this documentation if you -do not have OpenSSL installed. - -#### Installing OpenSSL via Homebrew - -We **highly recommend** that you use [Homebrew](http://brew.sh) to install OpenSSL. The PowerShell distribution for macOS -has built-in support for Homebrew's OpenSSL library paths. If you install with Homebrew, you will avoid -[security concerns](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#openssl) -around creating symbolic links in your `/usr/local/lib` path which are needed when using other means of installation. - -If you don't already have Homebrew installed, you can do so by downloading and installing Homebrew via this ruby script: - -```` -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -```` - -Once Homebrew is installed, run the following command: - -``` -brew install openssl -``` - -Restart VS Code after completing the installation and verify that the extension is working correctly. - -#### Installing OpenSSL via MacPorts - -If you prefer to use [MacPorts](https://www.macports.org/), you can run the following command to install OpenSSL: - -``` -sudo port install openssl -``` - -You will need to take an additional step once installation completes: - -``` -sudo ln -s /opt/local/lib/libcrypto.1.0.0.dylib /usr/local/lib/libcrypto.1.0.0.dylib -sudo ln -s /opt/local/lib/libssl.1.0.0.dylib /usr/local/lib/libssl.1.0.0.dylib -``` - -Thanks to [@MarlonRodriguez](https://github.com/MarlonRodriguez) for the tip! - -Restart VS Code after completing the installation and verify that the extension is working correctly. +[PowerShell Extension] for Visual Studio Code. + +## Script Analysis is Reporting False Errors + +Script analysis is provided by the [PSScriptAnalyzer] project on GitHub. +Please [open an issue there] if you are getting fault script diagnostics +(red and green squiggly lines under PowerShell in scripts). + +## Problems with Syntax Highlighting + +PowerShell syntax highlighting is not performed by the [PowerShell Extension]. +Instead syntax highlighting for VSCode, Atom, SublimeText and even GitHub is +provided by the [Editor Syntax] repository on GitHub. Please open any +[syntax highlighting issues there]. + +## Known Issues in the Extension + +- Highlighting/completions/command history don't work as I expect in the + Integrated Console - [#535] + - The Integrated Console implements a [custom host] + to work with VSCode, making it incompatible with + [PSReadLine] (the module providing these features in regular PowerShell). +- Command history is not preserved when debugging in the Integrated Console - + [#550] + - This feature is also provided by [PSReadLine]. +- Intellisense is slow - [#647] + - This is a known issue that we've been chipping away at. There doesn't seem + to be any one performance drain, but we've been trying to incrementally + improve performance bit-by-bit everywhere. +- Variable renaming doesn't work properly - [#261] + - PowerShell's usage of [dynamic scope] rather than [lexical scope] + makes it [formally undecidable] to statically rename variables correctly + (the only way to know for sure which `$x`s refer to the same variable is to + run the PowerShell script). + However, like with many features, we attempt a best effort. +- "Go to Definition" doesn't work through module imports - [#499] + - Again this is a best-effort task. +- Completions don't cycle when Tab is pressed like in the ISE - [#25] + - VSCode itself provides the user experience for completions, and they + currently don't allow us to customize this. +- My command that opens a dialog does nothing - [#410 (comment)] + - Check that the dialog hasn't opened behind VSCode. This is a known + [VSCode issue]. +- PowerShell classes don't have proper reference/symbol support - [#3] + - To maintain compatibility with PowerShell v3/v4 we use an older + PowerShell parsing API that does not support classes. A future version + of the [PowerShell Extension] [will break this compatibility] to support + classes, among other things. +- Document formatting takes a long time - [#984] + - Document formatting is provided by [PSScriptAnalyzer], but there + may be opportunities to improve our integration with it in the + [PowerShell Extension] too. +- `Write-Progress` doesn't output to the console - [#140] + +## Reporting an Issue + +If you experience a problem with the [PowerShell Extension]: + +1. Search through [existing issues] on GitHub. + In some circumstances, an issue may already be closed due to + a fix being merged but not yet released - so be sure to quickly + check closed issues as well. +2. Most features are provided by the client-agnostic [PowerShell Editor Services] + backend project that the extension leverages, so it's also worth a + [look there]. +3. If you don't see the issue you're experiencing, please [open a new issue]. + +## Opening a New Issue + +To open a new issue on the [PowerShell Extension], use our [GitHub issues page]. + +### Note on Security + +If you believe there is a security vulnerability in the [PowerShell Extension] +(or in [PowerShell Editor Services]), it **must** be reported directly to +secure@microsoft.com to allow for [Coordinated Vulnerability Disclosure]. +**Only** open an issue if secure@microsoft.com has confirmed that filing +an issue on GitHub is appropriate. + +[Editor Syntax]: https://github.com/PowerShell/EditorSyntax +[PSScriptAnalyzer]: https://github.com/PowerShell/PSScriptAnalyzer +[PSReadLine]: https://github.com/lzybkr/PSReadLine +[PowerShell Editor Services]: https://github.com/PowerShell/PowerShellEditorServices +[PowerShell Extension]: https:github.com/PowerShell/vscode-powershell + +[Coordinated Vulnerability Disclosure]: https://technet.microsoft.com/security/dn467923 +[custom host]: https://docs.microsoft.com/en-us/powershell/developer/hosting/custom-host-samples +[dynamic scope]: http://ig2600.blogspot.com/2010/01/powershell-is-dynamically-scoped-and.html +[existing issues]: https://github.com/PowerShell/vscode-powershell/issues +[formally undecidable]: https://en.wikipedia.org/wiki/Undecidable_problem +[GitHub issues page]: https://github.com/PowerShell/vscode-powershell/issues/new/choose +[lexical scope]: https://stackoverflow.com/questions/1047454/what-is-lexical-scope +[look there]: https://github.com/PowerShell/PowerShellEditorServices/issues +[open an issue]: https://github.com/PowerShell/vscode-powershell/issues/new/choose +[open a new issue]: #opening-a-new-issue +[open an issue there]: https://github.com/PowerShell/PSScriptAnalyzer/issues/new/choose +[Reporting Problems]: ../README.md#reporting-problems +[syntax highlighting issues there]: https://github.com/PowerShell/EditorSyntax/issues/new +[VSCode issue]: https://github.com/Microsoft/vscode/issues/42356 +[will break this compatibility]: https://github.com/PowerShell/vscode-powershell/issues/1310 + +[#3]: https://github.com/PowerShell/vscode-powershell/issues/3 +[#25]: https://github.com/PowerShell/vscode-powershell/issues/25 +[#140]: https://github.com/PowerShell/vscode-powershell/issues/140 +[#261]: https://github.com/PowerShell/vscode-powershell/issues/261 +[#410 (comment)]: https://github.com/PowerShell/vscode-powershell/issues/410#issuecomment-397531817 +[#499]: https://github.com/PowerShell/vscode-powershell/issues/499 +[#535]: https://github.com/PowerShell/vscode-powershell/issues/535 +[#550]: https://github.com/PowerShell/vscode-powershell/issues/550 +[#647]: https://github.com/PowerShell/vscode-powershell/issues/647 +[#984]: https://github.com/PowerShell/vscode-powershell/issues/984 \ No newline at end of file From 1f7d91c3503a7eb63c0b8c72f0cdd178591c4796 Mon Sep 17 00:00:00 2001 From: Robert Holt Date: Fri, 21 Sep 2018 11:56:09 -0700 Subject: [PATCH 03/10] Info on opening an issue --- docs/troubleshooting.md | 131 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 129 insertions(+), 2 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 0ca31cacea..c2558159e3 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -70,7 +70,127 @@ If you experience a problem with the [PowerShell Extension]: ## Opening a New Issue -To open a new issue on the [PowerShell Extension], use our [GitHub issues page]. +If you experience an issue with the [PowerShell Extension] and can't find +an existing issue for it, [open an issue on us on GitHub]. + +You can also open an issue directly from VSCode by entering the +[Command Palette] with Ctrl+Shift+P +(Cmd+Shift+P) and running the +`PowerShell: Upload Bug Report to GitHub` command. + +When opening an issue, keep in mind: + +- The fastest way to fixing a bug is reproducing it, and reproducing it + is easier with [more information]. +- The issue templates are designed to help you provide all the information + needed to solve your issue +- As Free and Open Source Software, the [PowerShell Extension] thrives on + the contributions of community members — if you're interested in + [tackling an issue], we always accept contributions and will help you + through the entire process. + +## Providing Information About Your Environment + +For solving most issues, the following information is important to provide: + +- Logs, which provide context for what was happening when the issue occurred + - Before sending through logs, try and reproduce the issue with + **log level set to Verbose** or **Diagnostic**. You can set this + in the [VSCode Settings] (Ctrl+,) with: + ```json + "powershell.developer.editorServicesLogLevel": "Verbose" + ``` + or for diagnostic logging: + ```json + "powershell.developer.editorServicesLogLevel": "Diagnostic" + ``` + After you have captured the issue with the log level turned up, + you may want to return it (since verbose logging can use disk space): + ```json + "powershell.developer.editorServicesLogLevel": "Normal" + ``` + - Logs are located at + ```powershell + $HOME/.vscode[-insiders]/extensions/ms-vscode.powershell-/logs/ + ``` + For example: + + ```powershell + $HOME/vscode/extensions/ms-vscode.powershell-1.8.4/logs + ``` + - In VSCode you can open and read the logs directly from the [Command Palette] + (Ctrl+Shift+P) + with `PowerShell: Open PowerShell Extension Logs Folder`. + - You can attach your logs to an issue by zipping them and drag/dropping + them onto your open issue description in the browser. + - If you prefer to share your logs privately, you can send them to + vscode-powershell@microsoft.com. Please still open an issue though + so we can track the work — other users may have the same issue. + +- [Your VSCode version], obtained from the Integrated Console + or PowerShell like this: + + ```shell + code -v + ``` + + If you are using VSCode Insiders, use this command: + + ```shell + code-insiders -v + ``` + + If VSCode is not on your path, you will get a message like + + ```text + code: The term 'code' is not recognized as the name of a cmdlet, ... + ``` + + in this case, use the file menu in VSCode and choose `Help`>`About` + (or `Code`>`About Visual Studio Code` on macOS) to get version information. + +- [Your installed PowerShell Extension version]: + + ```shell + code --list-extensions --show-versions + ``` + + With VSCode Insiders: + + ```shell + code-insiders --list-extensions --show-versions + ``` + + If VSCode isn't on your path use the [Command Palette] + (Ctrl+Shift+P) to enter + `Extensions: Show Installed Extensions` and list your extensions. + +- [Your PowerShell version table], which you can get + from the Integrated Console: + + ```powershell + > $PSVersionTable + Name Value + ---- ----- + PSVersion 6.1.0 + PSEdition Core + GitCommitId 6.1.0 + OS Microsoft Windows 10.0.18242 + Platform Win32NT + PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...} + PSRemotingProtocolVersion 2.3 + SerializationVersion 1.1.0.1 + WSManStackVersion 3.0 + ``` + +- Operating System Information + - Windows + - Your Windows version (e.g. 10) + - macOS + - Your macOS version (e.g. High Sierra 10.13.6) + - Linux + - `uname -a` + - Your distro and version (usually `lsb_release -a` is the best here) ### Note on Security @@ -86,21 +206,28 @@ an issue on GitHub is appropriate. [PowerShell Editor Services]: https://github.com/PowerShell/PowerShellEditorServices [PowerShell Extension]: https:github.com/PowerShell/vscode-powershell +[Command Palette]: https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette [Coordinated Vulnerability Disclosure]: https://technet.microsoft.com/security/dn467923 [custom host]: https://docs.microsoft.com/en-us/powershell/developer/hosting/custom-host-samples [dynamic scope]: http://ig2600.blogspot.com/2010/01/powershell-is-dynamically-scoped-and.html [existing issues]: https://github.com/PowerShell/vscode-powershell/issues [formally undecidable]: https://en.wikipedia.org/wiki/Undecidable_problem -[GitHub issues page]: https://github.com/PowerShell/vscode-powershell/issues/new/choose [lexical scope]: https://stackoverflow.com/questions/1047454/what-is-lexical-scope [look there]: https://github.com/PowerShell/PowerShellEditorServices/issues +[more information]: #providing-information-about-your-environment [open an issue]: https://github.com/PowerShell/vscode-powershell/issues/new/choose [open a new issue]: #opening-a-new-issue [open an issue there]: https://github.com/PowerShell/PSScriptAnalyzer/issues/new/choose +[open an issue on us on GitHub]: https://github.com/PowerShell/vscode-powershell/issues/new/choose [Reporting Problems]: ../README.md#reporting-problems [syntax highlighting issues there]: https://github.com/PowerShell/EditorSyntax/issues/new +[tackling an issue]:./development.md [VSCode issue]: https://github.com/Microsoft/vscode/issues/42356 +[VSCode Settings]: https://code.visualstudio.com/docs/getstarted/settings [will break this compatibility]: https://github.com/PowerShell/vscode-powershell/issues/1310 +[Your installed PowerShell Extension version]: https://code.visualstudio.com/docs/editor/extension-gallery#_list-installed-extensions +[Your PowerShell version table]: http://www.powertheshell.com/topic/learnpowershell/firststeps/psversion/ +[Your VSCode version]: https://code.visualstudio.com/docs/supporting/FAQ#_how-do-i-find-the-vs-code-version [#3]: https://github.com/PowerShell/vscode-powershell/issues/3 [#25]: https://github.com/PowerShell/vscode-powershell/issues/25 From 98df542a697f1876d9e3786dc5d018c85b64718d Mon Sep 17 00:00:00 2001 From: Robert Holt Date: Fri, 21 Sep 2018 13:35:26 -0700 Subject: [PATCH 04/10] Update README to point at troubleshooting doc --- README.md | 43 +++++-------------------------------------- 1 file changed, 5 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 272ea7cf75..58523fb922 100644 --- a/README.md +++ b/README.md @@ -71,45 +71,12 @@ iex (iwr https://git.io/vbxjj) ## Reporting Problems -If you're having trouble with the PowerShell extension, please follow these instructions -to file an issue on our GitHub repository: +If you experience any problems with the PowerShell Extension, see +[the troubleshooting docs](./docs/troubleshooting.md) for information +on diagnosing and reporting issues. -### 1. File an issue on our [Issues Page](https://github.com/PowerShell/vscode-powershell/issues) - -Make sure to fill in the information that is requested in the issue template as it -will help us investigate the problem more quickly. - -To automatically create a bug report from within the extension, open the Command pallet (Ctrl/Cmd+Shift+P) and run the *"Report a problem on GitHub"* command. Some basic information about your instance and powershell versions will be collected and inserted into a new GitHub issue. - -NOTE: If you believe that there is a security vulnerability in the PowerShell extension for VSCode, -it **must** be reported to [secure@microsoft.com](https://technet.microsoft.com/security/ff852094.aspx) to allow for [Coordinated Vulnerability Disclosure](https://technet.microsoft.com/security/dn467923). -**Only** file an issue, if secure@microsoft.com has confirmed filing an issue is appropriate. - -### 2. Capture verbose logs and send them to us - -If you're having an issue with crashing or other erratic behavior, add the following -line to your User Settings in Visual Studio Code: - -```json - "powershell.developer.editorServicesLogLevel": "Verbose" -``` - -Restart Visual Studio Code and try to reproduce the problem. Once you are done with -that, zip up the logs in the corresponding folder for your operating system: - -- **Windows**: `$HOME\.vscode\extensions\ms-vscode.PowerShell-\logs` -- **Linux and macOS**: `~/.vscode/extensions/ms-vscode.PowerShell-/logs` - -Alternatively, you can open the log folder using the Command pallet (Ctrl/Cmd+Shift+P) and running the *"Open powerShell Extension Logs Folder"* command. - -You have two options for sending us the logs: - - 1. If you are editing scripts that contain sensitive information (intellectual property, - deployment or administrative information, etc), e-mail the logs directly to - *vscode-powershell@microsoft.com*. - - 2. If you are editing scripts that don't contain sensitive information, you can drag and - drop your logs ZIP file into the GitHub issue that you are creating. +#### Security Note +For any security issues, please see [here](./docs/troubleshooting.md#note-on-security). ## Example Scripts From 12578195b3f8eae8893e0d39902d6d815213c372 Mon Sep 17 00:00:00 2001 From: Robert Holt Date: Fri, 21 Sep 2018 13:51:36 -0700 Subject: [PATCH 05/10] Fix omissions in troubleshooting doc --- docs/troubleshooting.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c2558159e3..ef0037f7fd 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -23,6 +23,7 @@ provided by the [Editor Syntax] repository on GitHub. Please open any - The Integrated Console implements a [custom host] to work with VSCode, making it incompatible with [PSReadLine] (the module providing these features in regular PowerShell). + Resolving this incompatibility is being actively worked on. - Command history is not preserved when debugging in the Integrated Console - [#550] - This feature is also provided by [PSReadLine]. @@ -75,7 +76,7 @@ an existing issue for it, [open an issue on us on GitHub]. You can also open an issue directly from VSCode by entering the [Command Palette] with Ctrl+Shift+P -(Cmd+Shift+P) and running the +(Cmd+Shift+P on macOS) and running the `PowerShell: Upload Bug Report to GitHub` command. When opening an issue, keep in mind: @@ -87,7 +88,7 @@ When opening an issue, keep in mind: - As Free and Open Source Software, the [PowerShell Extension] thrives on the contributions of community members — if you're interested in [tackling an issue], we always accept contributions and will help you - through the entire process. + at every step. ## Providing Information About Your Environment @@ -204,7 +205,7 @@ an issue on GitHub is appropriate. [PSScriptAnalyzer]: https://github.com/PowerShell/PSScriptAnalyzer [PSReadLine]: https://github.com/lzybkr/PSReadLine [PowerShell Editor Services]: https://github.com/PowerShell/PowerShellEditorServices -[PowerShell Extension]: https:github.com/PowerShell/vscode-powershell +[PowerShell Extension]: https:github.com/PowerShell/vscode-powershell/ [Command Palette]: https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette [Coordinated Vulnerability Disclosure]: https://technet.microsoft.com/security/dn467923 From e84694c1a1d88c7be564b793d989b840e5254fb7 Mon Sep 17 00:00:00 2001 From: Robert Holt Date: Fri, 21 Sep 2018 14:42:08 -0700 Subject: [PATCH 06/10] Update bug template to point to troubleshooting.md --- .github/ISSUE_TEMPLATE/Bug_report.md | 28 ++-- docs/troubleshooting.md | 216 +++++++++++++++++---------- 2 files changed, 152 insertions(+), 92 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index 1523d3554d..431ca50e7d 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -6,11 +6,8 @@ about: Report errors or unexpected behavior 🤔 ### System Details From 29f2388641295518999e2884916f98674450fb3d Mon Sep 17 00:00:00 2001 From: Robert Holt Date: Tue, 25 Sep 2018 09:54:28 -0700 Subject: [PATCH 10/10] Use pasteable version expression in bug report --- .github/ISSUE_TEMPLATE/Bug_report.md | 31 ++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index ab9a1a43ec..59e1b21008 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -24,21 +24,34 @@ attach it here by dropping the file into the description body. ### System Details -- Operating system name and version: -- VS Code version: -- PowerShell extension version: + + + +System Details Output +``` -> $PSVersionTable ``` ### Issue Description