From 2d1b99d82e5406fc58b2122c7aeefe8c14b0b887 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:04:47 -0700 Subject: [PATCH 01/10] Fix docs/Testing capitalization --- docs/{Testing => testing}/PesterDoAndDont.md | 0 docs/{Testing => testing}/Testing.md | 0 docs/{Testing => testing}/WritingPesterTests.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename docs/{Testing => testing}/PesterDoAndDont.md (100%) rename docs/{Testing => testing}/Testing.md (100%) rename docs/{Testing => testing}/WritingPesterTests.md (100%) diff --git a/docs/Testing/PesterDoAndDont.md b/docs/testing/PesterDoAndDont.md similarity index 100% rename from docs/Testing/PesterDoAndDont.md rename to docs/testing/PesterDoAndDont.md diff --git a/docs/Testing/Testing.md b/docs/testing/Testing.md similarity index 100% rename from docs/Testing/Testing.md rename to docs/testing/Testing.md diff --git a/docs/Testing/WritingPesterTests.md b/docs/testing/WritingPesterTests.md similarity index 100% rename from docs/Testing/WritingPesterTests.md rename to docs/testing/WritingPesterTests.md From 7675de8d74810b28d3ae7cafdfd8174df9a310d6 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:08:05 -0700 Subject: [PATCH 02/10] Link Pester readme to Pester Do and Don't --- test/powershell/README.md | 99 ++------------------------------------- 1 file changed, 3 insertions(+), 96 deletions(-) diff --git a/test/powershell/README.md b/test/powershell/README.md index 21ba2f1c97..ec93e0f529 100644 --- a/test/powershell/README.md +++ b/test/powershell/README.md @@ -1,6 +1,9 @@ Pester Testing Test Guide ========================= +Also see the [Pester Do and Don't](../../docs/testing/PesterDoAndDont.md) +document. + Running Pester Tests -------------------- @@ -47,99 +50,3 @@ Pending When writing a test that should pass, but does not, please do not skip or delete the test, but use `It "Should Pass" -Pending` to mark the test as pending, and file an issue on GitHub. - -Who this is for ---------------- - -Cmdlet behavior is validated using the Pester testing framework. The -purpose of this document is to create a single standard to maximize -unit test coverage while minimizing confusion on expectations. What -follows is a working document intended to guide those writing Pester -unit tests for PowerShell. - -Unit testing is done not only to validate that the block of code works -as expected, but also to assist the developer to know precisely where -in the code to look; in some cases, seeing the source code may inspire -better unit tests. In many cases, a unit test *is* the only documented -specification. Fortunately, the MSDN is a great source of information -about Cmdlets. - -Test suites need to be created and many cmdlets added and unit-tested. -The following list is to be used to guide the thought process of the -developer in writing a suite in minimal time, while enhancing quality. - -Test suites should proceed as functional and system tests of the -cmdlets, and the code treated as a black box for the purpose of test -suite design. - -Testing Standards ------------------ - -### Readability - -Every effort should be made to maximize readability of code. Code is -written for the developer in the future to debug- not for the -developer writing the code. - -1) When assertions are on consecutive lines, the pipes should line up: - -```sh -MyFirstCondition | Should Be 0 -MySecondCondition | Should Be 1 -``` - -This is less readable than: - -```sh -MyFirstCondition | Should Be 0 -MySecondCondition | Should Be 1 -``` - -So the second section of code should instead be used. The same style -should be followed for assignments of variables on consecutive lines: - -```sh -$var1 = -$variable2 = -$var3 = -$typeCollection1 = -$object1 = -... etc -``` - -is much less readable than - -```sh -$var1 = -$variable2 = -$var3 = -$typeCollection1 = -$object1 = -... etc -``` - -So all assignment statements must be aligned. - -Other style standards are no less important to readability of the code: - -- Use readable and meaningful variable name when assigning variables. - -- Do not make large functions. Tests should be simple: define -> - manipulate -> assert - -- Do not use tabs. Tabs are rendered differently depending upon the - machine. This greatly affects readability. - -- Remove the first 3 auto-generated lines of each .Tests.ps1 file. - This is created automatically by Pester and is unnecessary. Each - .Test.ps1 file should begin with a Describe block. - -- Discard the auto-generated function file that is generated in tandem - with the .Tests.ps1 file - -- Name the test file "Test- when you create a new test - fixture. - -- Each test describes a behavior- use the word "Should" at the - beginning of each test description- so it reads "It 'Should..." - From 1aa6a4904bcba172d647898992b77663973c32bc Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:10:25 -0700 Subject: [PATCH 03/10] Update Linux installation documentation --- docs/installation/linux.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/installation/linux.md b/docs/installation/linux.md index 803a94ae5d..8843e4d8c1 100644 --- a/docs/installation/linux.md +++ b/docs/installation/linux.md @@ -6,7 +6,7 @@ Supports Ubuntu 14.04, CentOS 7.1, and OS X 10.11. Once the package is installed, `powershell` will be in your path, ready to be launched from a terminal. It will read `~/.powershell/profile.ps1` for your user profile, and -`/opt/microsoft/powershell/Microsoft.PowerShellCore_profile.ps1` for +`/opt/microsoft/powershell/Microsoft.PowerShell_profile.ps1` for the host profile. Similarly, it will search `~/.powershell/Modules` and @@ -20,32 +20,32 @@ Ubuntu 14.04 ============ Using a stock Ubuntu 14.04 image, download the -`powershell_0.3.0-1_amd64.deb` file, and then execute the following: +`powershell_0.4.0-1_amd64.deb` file, and then execute the following: ```sh sudo apt-get install libunwind8 libicu52 -sudo dpkg -i powershell_0.3.0-1_amd64.deb +sudo dpkg -i powershell_0.4.0-1_amd64.deb ``` CentOS 7.1 ========== Using a stock CentOS 7.1 image, download the -`powershell-0.3.0-1.x86_64.rpm` file, and then execute the following: +`powershell-0.4.0-1.x86_64.rpm` file, and then execute the following: ```sh -sudo yum install powershell-0.3.0-1.x86_64.rpm +sudo yum install powershell-0.4.0-1.x86_64.rpm ``` OS X 10.11 ========== -Using an OS X 10.11 machine, download the `powershell-0.3.0.pkg` file, +Using an OS X 10.11 machine, download the `powershell-0.4.0.pkg` file, double-click it, and follow the prompts. Or install it from the terminal: ```sh -sudo installer -pkg powershell-0.3.0.pkg -target / +sudo installer -pkg powershell-0.4.0.pkg -target / ``` Note that because OS X is a derivation of BSD, instead of `/opt`, the From d1f6adb0a35b5a9af4997e6227474739ce8885b0 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:14:17 -0700 Subject: [PATCH 04/10] MMIN known issue is fixed --- docs/KNOWNISSUES.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index f109886248..a95c8b773c 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -7,12 +7,6 @@ temporarily from `Microsoft.PowerShell.Commands.Management` because we cannot resolve `[Shell32.ShellFolderItem]` for FullCLR builds. This must be fixed ASAP. -## `Microsoft.Management.Infrastructure.Native` - -Windows builds currently use the native stub; this should be replaced with -actual compilation of the managed C++ library on Windows (with the stub used on -Linux). - ## CorePS Eventing Library The Eventing library reimplementation for Core PowerShell does not exist on From ac55b037ae7b2207131481f75651bdbd4491b1fc Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:16:08 -0700 Subject: [PATCH 05/10] Eventing known issue is fixed --- docs/KNOWNISSUES.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index a95c8b773c..350eaaab1f 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -7,13 +7,6 @@ temporarily from `Microsoft.PowerShell.Commands.Management` because we cannot resolve `[Shell32.ShellFolderItem]` for FullCLR builds. This must be fixed ASAP. -## CorePS Eventing Library - -The Eventing library reimplementation for Core PowerShell does not exist on -Linux, and so the ETW stub is used via a `#if LINUX` guard. On Windows, this -library now exists, but its build needs to be ported to .NET CLI. Until then, -the stub is also used with a `#if ETW` guard. - ## xUnit The xUnit tests can only be run on Linux. From f75b39e5cda4dcf1aee5ce2d7be3daf2f37f8dd7 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:21:28 -0700 Subject: [PATCH 06/10] PSRP known issues removed Since it was decoupled from this repo. --- docs/KNOWNISSUES.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index 350eaaab1f..e0331eb38a 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -17,15 +17,6 @@ Performance issues have been seen in some scenarios, such as nested SSH sessions. We believe this is likely an issue with `Console.ReadKey()` and are investigating. -## Remoting - -Only basic authentication is implemented - -Multiple sessions are not yet supported - -Server shut-down is not complete (must restart `omiserver` after a session is -completed. - ## Unavailable cmdlets This project includes the CoreCLR versions of the `Commands.Management`, From 1381140f6e05c736c17d7d61c453b4b8b0558352 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:36:52 -0700 Subject: [PATCH 07/10] Add sessions known issue --- docs/KNOWNISSUES.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index e0331eb38a..9c964d16ca 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -17,6 +17,11 @@ Performance issues have been seen in some scenarios, such as nested SSH sessions. We believe this is likely an issue with `Console.ReadKey()` and are investigating. +## Sessions + +PowerShell sessions do not work because of remoting requirements, so +`New-PSSession` etc. crash. + ## Unavailable cmdlets This project includes the CoreCLR versions of the `Commands.Management`, From e140e215bb615366f53d6bdf2c38910991cd213e Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:43:16 -0700 Subject: [PATCH 08/10] Add aliases known issue --- docs/KNOWNISSUES.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index 9c964d16ca..2b205feb12 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -22,6 +22,14 @@ investigating. PowerShell sessions do not work because of remoting requirements, so `New-PSSession` etc. crash. +## Aliases + +The aliases that conflict with native Linux / OS X commands are removed. This is +an open discussion in issue [#929][]. See commit 7d9f43966 for their removal, +and 3582bb421 for the merge. + +[#929]: https://github.com/PowerShell/PowerShell/issues/929 + ## Unavailable cmdlets This project includes the CoreCLR versions of the `Commands.Management`, From e2f4b16c2f4fdb9c0ee014d5f6233ebacb0f1483 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:47:13 -0700 Subject: [PATCH 09/10] Add team coordination link to internal docs --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 16701deefc..677f393a4e 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,8 @@ Team coordination - [Waffle.io scrum board](https://waffle.io/PowerShell/PowerShell) - [VSO items](https://aka.ms/openps) - [PowerShell subsystem maintainers](https://aka.ms/psowners) -- [Internal documents](https://aka.ms/pscore) +- [Automation Sharepoint](https://aka.ms/pscore) +- [Internal Open PowerShell Documents](https://github.com/PowerShell/Internal-PowerShellTeam-Tools/tree/master/OpenPowerShellDocs) If you encounter any problems, see the [known issues](KNOWNISSUES.md), search the [issues][], and if all else fails, open a new issue. From 60f6e0501752cb8a2d4ab4427a8e938b4a753754 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 18 May 2016 10:50:00 -0700 Subject: [PATCH 10/10] Add non-interactive console known issue --- docs/KNOWNISSUES.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index 2b205feb12..db2cceab91 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -17,6 +17,14 @@ Performance issues have been seen in some scenarios, such as nested SSH sessions. We believe this is likely an issue with `Console.ReadKey()` and are investigating. +## Non-interactive console bugs + +The `ConsoleHost` is buggy when running under an environment without a proper +TTY. This is due to exceptions thrown in the `RawUI` class from `System.Console` +that are silenced in the formatting subsystem. See issue [#984][]. + +[#984]: https://github.com/PowerShell/PowerShell/issues/984 + ## Sessions PowerShell sessions do not work because of remoting requirements, so