Merge pull request #990 from PowerShell/andschwa/docs
Documentation update
This commit is contained in:
Andy Schwartzmeyer
commit
8ce3dbb7d9
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 = <expression 1>
|
||||
$variable2 = <expression 2>
|
||||
$var3 = <expression 3>
|
||||
$typeCollection1 = <expression 4>
|
||||
$object1 = <expression>
|
||||
... etc
|
||||
```
|
||||
|
||||
is much less readable than
|
||||
|
||||
```sh
|
||||
$var1 = <expression 1>
|
||||
$variable2 = <expression 2>
|
||||
$var3 = <expression 3>
|
||||
$typeCollection1 = <expression 4>
|
||||
$object1 = <expression 5>
|
||||
... 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-<cmdlet name > 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..."
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue