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. diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index f109886248..db2cceab91 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -7,19 +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 -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. @@ -30,14 +17,26 @@ 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 +## Non-interactive console bugs -Only basic authentication is implemented +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][]. -Multiple sessions are not yet supported +[#984]: https://github.com/PowerShell/PowerShell/issues/984 -Server shut-down is not complete (must restart `omiserver` after a session is -completed. +## Sessions + +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 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 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 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..." -