Merge branch 'master' of https://www.github.com/powershell/powershell …

…into jianyunt/docs

README.md

@@ -20,10 +20,10 @@ You can download and install a PowerShell package for any of the following platf
 
 | Platform     | Releases           | How to Install                 |
 |--------------|--------------------|--------------------------------|
-| Windows      | [.msi][rl-windows] | [How to Install][in-windows] |
-| Ubuntu 14.04 | [.deb][rl-ubuntu]  | [How to Install][in-ubuntu]  |
-| CentOS 7     | [.rpm][rl-centos]  | [How to Install][in-centos]  |
-| OS X 10.11   | [.pkg][rl-osx]     | [How to Install][in-osx]     |
+| Windows      | [.msi][rl-windows] | [Instructions][in-windows] |
+| Ubuntu 14.04 | [.deb][rl-ubuntu]  | [Instructions][in-ubuntu]  |
+| CentOS 7     | [.rpm][rl-centos]  | [Instructions][in-centos]  |
+| OS X 10.11   | [.pkg][rl-osx]     | [Instructions][in-osx]     |
 
 [rl-windows]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/PowerShell_6.0.0.7.msi
 [rl-ubuntu]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/powershell_6.0.0-alpha.7-1_amd64.deb

docs/building/linux.md

@@ -106,7 +106,7 @@ Start-PSBuild
 Congratulations! If everything went right, PowerShell is now built.
 The `Start-PSBuild` script will output the location of the executable:
 
-`./src/powershell/bin/Linux/netcoreapp1.0/ubuntu.14.04-x64/powershell`.
+`./src/powershell-unix/bin/Linux/netcoreapp1.0/ubuntu.14.04-x64/powershell`.
 
 You should now be running the `powershell` that you just built, if your run the above executable.
 You can run our cross-platform Pester tests with `Start-PSPester`, and our xUnit tests with `Start-PSxUnit`.
@@ -129,7 +129,7 @@ make test
 popd
 ```
 
-This library will be emitted in the `src/powershell` project, 
+This library will be emitted in the `src/powershell-unix` project,
 where `dotnet` consumes it as "content" and thus automatically deploys it.
 
 Build the managed projects
@@ -141,7 +141,7 @@ The `--configuration Linux` flag is necessary to ensure that the preprocessor de
 
 ```sh
 dotnet restore
-cd src/powershell
+cd src/powershell-unix
 dotnet build --configuration Linux
 ```
 

docs/building/osx.md

@@ -76,6 +76,6 @@ download the `pkg` from our GitHub releases page using your browser, complete th
 start a `powershell` session, and use `Start-PSBuild` from the module.
 
 The output directory will be slightly different because your runtime identifier is different.
-PowerShell will be at `./src/powershell/bin/Linux/netcoreapp1.0/osx.10.11-x64/powershell`,
+PowerShell will be at `./src/powershell-unix/bin/Linux/netcoreapp1.0/osx.10.11-x64/powershell`,
 or `osx.10.10` depending on your operating system version.
 Note that configration is still `Linux` because it would be silly to make yet another separate configuration when it's used soley to work-around a CLI issue.

docs/building/windows-core.md

@@ -72,7 +72,7 @@ Start-PSBuild
 ```
 
 Congratulations! If everything went right, PowerShell is now built and
-executable as `./src/powershell/bin/Debug/netcoreapp1.0/win10-x64/powershell`.
+executable as `./src/powershell-win-core/bin/Debug/netcoreapp1.0/win10-x64/powershell`.
 
 This location is of the form
 `./[project]/bin/[configuration]/[framework]/[rid]/[binary name]`, and our

docs/building/windows-full.md

@@ -48,14 +48,11 @@ Build using our module
 Use `Start-PSBuild -FullCLR` from the `build.psm1`
 module.
 
-Because the `ConsoleHost` project (*not* the `Host` project) is a
-library and not an application (in the sense that .NET CLI does not
-emit a native executable using .NET Core's `corehost`), it targets the
-framework `netstandard1.6`, *not* `netcoreapp1.0`, and the build
-output will *not* have a runtime identifier in the path.
+The output location of `powershell.exe` will be
 
-Thus the output location of `powershell.exe` will be
-`./src/Microsoft.PowerShell.ConsoleHost/bin/Debug/net451/powershell.exe`
+```
+.\src\powershell-win-full\bin\Debug\net451\win10-x64\publish\powershell.exe
+```
 
 Build manually
 ==============
@@ -99,7 +96,7 @@ This command has a reasonable default to run `powershell.exe` from the build out
 If you are building an unusual configuration (i.e. not `Debug`), you can explicitly specify path to the bin directory
 
 ```powershell
-Start-DevPowerShell -FullCLR -binDir .\src\Microsoft.PowerShell.ConsoleHost\bin\Debug\net451
+Start-DevPowerShell -FullCLR -binDir .\src\powershell-win-full\bin\Debug\net451\win10-x64\publish
 ```
 
 Or more programmatically:

docs/installation/linux.md

@@ -22,7 +22,7 @@ sudo apt-get install libunwind8 libicu52
 sudo dpkg -i powershell_6.0.0-alpha.7-1_amd64.deb
 ```
 
-> Please note that that Ubuntu 16.04 is not yet supported, but coming soon!
+> Please note that Ubuntu 16.04 is not yet supported, but coming soon!
 
 [Ubuntu 14.04]: http://releases.ubuntu.com/14.04/
 

docs/testing-guidelines/PesterDoAndDont.md

@@ -1,23 +1,34 @@
 ## Do
-1. Name your files <description>.tests.ps1
+1. Name your files <descriptivetest>.tests.ps1
 2. Keep tests simple
 	1. Test only what you need
 	2. Reduce dependencies
-3. Be sure to tag your Describe blocks with "inner" and "outer"
-4. Make sure that Describe/Context/It descriptions are useful
+3. Be sure to tag your `Describe` blocks based on their purpose
+	1. Tag `CI` indicates that it will be run as part of the continuous integration process. These should be unit test like, and generally take less than a second.
+	2. Tag `Feature` indicates a higher level feature test (we will run these on a regular basis), for example, tests which go to remote resources, or test broader functionality
+	3. Tag `Scenario` indicates tests of integration with other features (these will be run on a less regular basis and test even broader functionality than feature tests.
+4. Make sure that `Describe`/`Context`/`It` descriptions are useful
 	1. The error message should not be the place where you describe the test
-5. Use "Context" to group tests
-	1. Multiple Contexts can help you group your test suite into logical sections
-6. Use BeforeAll/AfterAll/BeforeEach/AfterEach instead of custom initiators
-7. Use Try-Catch for expected errors and check $_.fullyQualifiedErrorId
-8. Loop It blocks for checking multiple properties
+5. Use `Context` to group tests
+	1. Multiple `Context` blocks can help you group your test suite into logical sections
+6. Use `BeforeAll`/`AfterAll`/`BeforeEach`/`AfterEach` instead of custom initiators
+7. Prefer Try-Catch for expected errors and check $_.fullyQualifiedErrorId (don't use `should throw`)
+8. Use `-testcases` when iterating over multiple `It` blocks
 9. Use code coverage functionality where appropriate
-10. Use Mock functionality when you don't have your entire environment
-11. Avoid free code in a Describe block
-	1. Use `[Before|After][Each|All]` _see Free Code in a Describe block_
+10. Use `Mock` functionality when you don't have your entire environment
+11. Avoid free code in a `Describe` block
+	1. Use `[Before|After][Each|All]` see [Free Code in a Describe block](WritingPesterTests.md#free-code-in-a-describe-block)
+12. Avoid creating or using test files outside of TESTDRIVE:
+    1. TESTDRIVE: has automatic clean-up
+13. Keep in mind that we are creating cross platform tests
+    1. Avoid using the registry
+    2. Avoid using COM
+14. Avoid being too specific about the _count_ of a resource as these can change platform to platform
+    1. ex: checking for the count of loaded format files, check rather for format data for a specific type
 
 ## Don't
-1. Have too many evaluations in a single It block
-	1. The first "Should" failure will stop that block
-2. Don't use "Should" anywhere but within an "It" Block
-
+1. Don't have too many evaluations in a single It block
+	1. The first `Should` failure will stop that block
+2. Don't use `Should` outside of an `It` Block
+3. Don't use the word "Error" or "Fail" to test a positive case
+    1. ex: "Get-Childitem TESTDRIVE: shouldn't fail", rather "Get-ChildItem should be able to retrieve file listing from TESTDRIVE"