PowerShell · TravisEz13 · Mar 5, 2019 · Jan 24, 2019 · Jan 24, 2019 · Feb 9, 2019
@@ -2,7 +2,7 @@
 
 The docs folder in this repo contains a lot of documentation about the PowerShell source code and build environment.
 It also has contained documentation about installing and using PowerShell.
-That documentation really belongs in the [PowerShell/PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repo.
+That documentation belongs in the [PowerShell/PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repo.
 
 We are in the process of migrating the user-focused articles to the docs repo.
 This file records which files have been migrated.

@@ -143,7 +143,7 @@ Be sure to build and test for all supported architectures: `x86`, `x64`, `x64_ar
 The `x64_arm` and `x64_arm64` architectures mean that the host system needs to be x64 to cross-compile to ARM.
 When building for multiple architectures, be sure to use the `-clean` switch as cmake will cache the previous run and the wrong compiler will be used to generate the subsequent architectures.
 
-After that, the binary `pwrshplugin.dll`, its PDB file, and `powershell.core.instrumentation.dll` will be placed under 'src\powershell-win-core'.
+After that, the binary `pwrshplugin.dll`, its PDB file, and `powershell.core.instrumentation.dll` will be placed under `src\powershell-win-core`.
 
 To create a new NuGet package for `pwrshplugin.dll`, first you need to get the `psrp.windows.nuspec` from an existing `psrp.windows` package.
 You can find it at `~/.nuget/packages/psrp.windows` on your windows machine if you have recently built PowerShell on it.

@@ -30,7 +30,7 @@ Add another package source with name `powershell-core` and source `https://power
 ![Step4](./Images/Step4.png)
 
 1. Add the code of cmdlet:
-    ```CSharp
+    ```csharp
     using System.Management.Automation;  // PowerShell namespace.
 
     namespace SendGreeting
@@ -90,7 +90,7 @@ It should find `PowerShellStandard.Library` package, select it and it will show
 ![StdImage3](./Images/Std3.png)
 
 1. Add the code of cmdlet:
-    ```CSharp
+    ```csharp
     using System.Management.Automation;  // PowerShell namespace.
 
     namespace SendGreeting
@@ -128,4 +128,4 @@ It should find `PowerShellStandard.Library` package, select it and it will show
 On PowerShell Core on Linux:
 ![StdImage62](./Images/Std62.png)
 On Windows PowerShell on Windows (this requires [.NET Framework 4.7.1](https://github.com/Microsoft/dotnet-framework-early-access/blob/master/instructions.md)):
-![StdImage63](./Images/Std63.png)
+![StdImage63](./Images/Std63.png)
@@ -5,6 +5,7 @@
 * [**PowerShell Committee**](#powershell-committee): A committee of project owners who are responsible for design decisions,
   approving [RFCs][RFC-repo], and approving new maintainers/committee members
 * [**Repository maintainer**](#repository-maintainers): An individual responsible for merging pull requests (PRs) into `master` when all requirements are met (code review, tests, docs, and RFC approval as applicable).
+
   Repository Maintainers are the only people with write permissions for the `master` branch.
 * [**Area experts**](#area-experts): People who are experts for specific components (e.g. PSReadline, the parser) or technologies (e.g. security, performance).
   Area experts are responsible for code reviews, issue triage, and providing their expertise to others.

@@ -1,5 +1,4 @@
-Visual Studio Code
-==================
+# Visual Studio Code
 
 [Experimental .NET Core Debugging in VS Code][core-debug] enables
 cross-platform debugging with the [Visual Studio Code][vscode] editor.
@@ -48,8 +47,7 @@ careful not to commit such a change.)
 [OmniSharp]: https://github.com/OmniSharp/omnisharp-vscode
 [vscclrdebugger]: https://aka.ms/vscclrdebugger
 
-PowerShell
-==========
+## PowerShell
 
 The `Trace-Command` cmdlet can be used to enable tracing of certain PowerShell
 subsystems. Use `Get-TraceSource` for a list of tracers:
@@ -91,8 +89,7 @@ The `-PSHost` specifies the sink, in this case the console host,
 so we can see the tracing messages.
 The `-Name` chooses the list of tracers to enable.
 
-LLDB with SOS plug-in
-=====================
+## LLDB with SOS plug-in
 
 The `./tools/debug.sh` script can be used to launch PowerShell inside of LLDB
 with the SOS plug-in provided by .NET Core. This provides an additional way to
@@ -104,14 +101,12 @@ The script is self-documented and contains a link to the
 
 [clr-debug]: https://github.com/dotnet/coreclr/blob/master/Documentation/building/debugging-instructions.md#debugging-coreclr-on-linux
 
-corehost
-========
+## `corehost`
 
 The native executable produced by .NET CLI will produce trace output
 if launched with `COREHOST_TRACE=1 ./powershell`.
 
-CoreCLR PAL
-===========
+## CoreCLR PAL
 
 The native code in the CLR has debug channels to selectively output
 information to the console. These are controlled by the
@@ -123,8 +118,7 @@ you will need to narrow your scope.
 
 [header]: https://github.com/dotnet/coreclr/blob/release/1.0.0/src/pal/src/include/pal/dbgmsg.h
 
-Debugging .NET Core
-===================
+## Debugging .NET Core
 
 The .NET Core libraries downloaded from NuGet and shipped with PowerShell are release versions.
 This means that `PAL_DBG_CHANNELS` will not work with them,
@@ -134,16 +128,14 @@ but should prove useful.
 
 They are currently written for Linux and are meant only as a shortcut means to debug.
 
-Build and deploy CoreCLR
-------------------------
+## Build and deploy CoreCLR
    
 * Clone CoreCLR: `git clone -b release/1.0.0 https://github.com/dotnet/coreclr.git`
 * Follow [building instructions](https://github.com/dotnet/coreclr/blob/release/1.0.0/Documentation/building/linux-instructions.md)
 * Wait for `./build.sh` to finish
 * Overwrite PowerShell libraries: `cp bin/Product/Linux.x64.Debug/*{so,dll} /path/to/powershell/`
 
-Build and deploy CoreFX
------------------------
+## Build and deploy CoreFX
 
 * Clone CoreFX: `git clone -b release/1.0.0 https://github.com/dotnet/corefx.git`
 * Follow [building instructions](https://github.com/dotnet/corefx/blob/release/1.0.0/Documentation/building/unix-instructions.md)

@@ -4,29 +4,33 @@ We have a serious commitment to backwards compatibility with all earlier version
 
 Below is a summary of our approach to handing breaking changes including what kinds of things constitute breaking changes, how we categorize them, and how we decide what we're willing to take.
 
-Note that these rules only apply to existing stable features that have shipped in a supported release. New features marked as “in preview” that are still under development may be modified from one preview release to the next. These are not considered breaking changes.
+Note that these rules only apply to existing stable features that have shipped in a supported release. New features marked as “in preview” that are still under development may be modified from one preview release to the next.
+These are **not** considered breaking changes.
 
 To help triage breaking changes, we classify them in to four buckets:
 
 1. Public Contract
-2. Reasonable Grey Area
-3. Unlikely Grey Area
-4. Clearly Non-Public
+1. Reasonable Grey Area
+1. Unlikely Grey Area
+1. Clearly Non-Public
 
 ## Bucket 1: Public Contract
 
 Any change that is a clear violation of the public contract.
 
-### Unacceptable changes:
+### Unacceptable changes
 
 + A code change that results in a change to the existing behavior observed for a given input with an API, protocol or the PowerShell language.
-+ Renaming or removing a public type, type member, or type parameter; renaming or removing a cmdlet or cmdlet parameter (note: it is possible to rename a cmdlet parameter if a parameter alias is added. This is an acceptable solution for PowerShell scripts but may 
BE95
break .NET code that depends on the name of the original member on the cmdlet object type.)
++ Renaming or removing a public type, type member, or type parameter; renaming or removing a cmdlet or cmdlet parameter (note: it is possible to rename a cmdlet parameter if a parameter alias is added.
+
+This is an acceptable solution for PowerShell scripts but may break .NET code that depends on the name of the original member on the cmdlet object type.)
+
 + Decreasing the range of accepted values within a given parameter.
 + Changing the value of a public constant or enum member; changing the type of a cmdlet parameter to a more restrictive type.
     + Example: A cmdlet with a parameter -p1 that was previously type as [object] cannot be changed to be or a more restrictive type such as [int].
 + Making an incompatible change to any protocol without increasing the protocol version number.
 
-### Acceptable changes:
+### Acceptable changes
 
 + Any existing behavior that results in an error message generally may be changed to provide new functionality.
 + A new instance field is added to a type (this impacts .NET serialization but not PowerShell serialization and so is considered acceptable.)
@@ -44,7 +48,8 @@ Examples:
 + Change in parsing of input and throwing new errors (even if parsing behavior is not specified in the docs)
     + Example: a script may be using a JSON parser that is forgiving to minor syntactic errors in the JSON text. Changing that parser to be more rigorous in its processing would result in errors being thrown when no error was generated in the past thus breaking scripts.
 
-Judiciously making changes in these type of features require judgement: how predictable, obvious, consistent was the behavior? In general, a significant external preview of the change would need to be done also possibly requiring an RFC to be created to allow for community input on the proposal.
+Judiciously making changes in these type of features require judgement: how predictable, obvious, consistent was the behavior?
+In general, a significant external preview of the change would need to be done also possibly requiring an RFC to be created to allow for community input on the proposal.
 
 ## Bucket 3: Unlikely Grey Area
 
@@ -68,14 +73,14 @@ Examples:
 
 + Changes to internal APIs that break private reflection
 
-It is impossible to evolve a code base without making such changes, so we don't require up-front approval for these, but we will sometimes have to go back and revisit such change if there's too much pain inflicted on the ecosystem through a popular app or library.
+It is impossible to evolve a code base without making such changes, so we don't require up-front approval for these, but we will sometimes have to go back and
+revisit such change if there's too much pain inflicted on the ecosystem through a popular app or library.
 
-# What This Means for Contributors
+## What This Means for Contributors
 
 + All bucket 1, 2, and 3 breaking changes require contacting team at @powershell/powershell.
 + If you're not sure into which bucket a given change falls, contact us as well.
 + It doesn't matter if the existing behavior is "wrong", we still need to think through the implications. PowerShell has been in broad use for over 10 years so we be must be extremely sensitive to breaking existing users and scripts.
 + If a change is deemed too breaking, we can help identify alternatives such as introducing a new API or cmdlet and obsoleting the old one.
 
 Request for clarifications or suggested alterations to this document should be done by opening issues against this document.
-
@@ -155,7 +155,7 @@ such as `password`, `crypto`, `encryption`, `decryption`, `certificate`, `authen
 
 When facing a PR with such changes,
 the reviewers should request a designated security Subject Matter Expert (SME) to review the PR.
-Currently, @PaulHigin and @TravisEz13 are our security SMEs.
+Currently, [@PaulHigin](https://github.com/PaulHigin) and [@TravisEz13](https://github.com/TravisEz13) are our security SMEs.
 See [CODEOWNERS](../../.github/CODEOWNERS) for more information about the area experts.
 
 ## Best Practices
@@ -165,7 +165,7 @@ See [CODEOWNERS](../../.github/CODEOWNERS) for more information about the area e
 * Avoid a method that is too long and complex.
   In such case, separate it to multiple methods or even a nested class as you see fit.
 
-* Use `using` statement instead of `try/finally` if the only code in the `finally` block is to call the `Dispose` method.
+* Use the `using` statement instead of `try/finally` if the only code in the `finally` block is to call the `Dispose` method.
 
 * Use of object initializers (e.g. `new Example { Name = "Name", ID = 1 }`) is encouraged for better readability,
   but not required.

@@ -9,33 +9,32 @@ We are using our own `Start-ResGen` to generate them.
 
 Usually it's called as part of the regular build with
 
-```
-PS C:\> Start-PSBuild -ResGen
+```powershell
+Start-PSBuild -ResGen
 ```
 
 If you see compilation errors related to resources, try to call `Start-ResGen` explicitly.
 
-```
-PS C:\> Start-ResGen
+```powershell
+Start-ResGen
 ```
 
 ## Editing `.resx` files
 
-**Don't edit** `.resx` files from Visual Studio. 
+**Don't edit** `.resx` files from Visual Studio.
 It will try to create `.cs` files for you and you will get whole bunch of hard-to-understand errors.
 
-To edit a resource file, use any **plain text editor**. 
+To edit a resource file, use any **plain text editor**.
 A resource file is a simple XML file, and it's easy to edit.
 
-
 ## Convert `.txt` resource files into `.resx` files
 
 `dotnet cli` doesn't support embedding old-fashioned `.txt` resource.
 You can do a one-time conversion of `.txt` resources into `.resx` files with a helper function:
 
-```
+```powershell
 # example, converting all .txt resources under src\Microsoft.WSMan.Management\resources
-PS C:\> Convert-TxtResourceToXml -Path src\Microsoft.WSMan.Management\resources
+Convert-TxtResourceToXml -Path src\Microsoft.WSMan.Management\resources
 ```
 
 `.resx` files would be placed next to `.txt` files.
@@ -1,14 +1,12 @@
-Working with PowerShell repository
-==================================
+# Working with PowerShell repository
 
-#### Get the code for the first time
+## Get the code for the first time
 
 ```sh
-git clone https://github.com/PowerShell/PowerShell.git
+git clone https://github.com/PowerShell/PowerShell.git --branch=master
 ```
 
-Branches
----------
+## Branches
 
 * Don't commit your changes directly to master.
   It will make the collaborative workflow messy.
@@ -19,13 +17,13 @@ Branches
     You must never EVER destroy other peoples history. You must not rebase commits other people did.
     Basically, if it doesn't have your sign-off on it, it's off limits: you can't rebase it, because it's not yours."
 
-#### Understand branches
+### Understand branches
 
 * **master** is the branch with the latest and greatest changes.
   It could be unstable.
 * Send your pull requests to **master**.
 
-#### Sync your local repo
+### Sync your local repo
 
 Use **git rebase** instead of **git merge** and **git pull**, when you're updating your feature-branch.
 
@@ -39,7 +37,7 @@ git fetch --all -p
 git rebase origin/master
 ```
 
-#### More complex scenarios
+### More complex scenarios
 
 Covering all possible git scenarios is behind the scope of the current document.
 Git has excellent documentation and lots of materials available online.
@@ -50,14 +48,12 @@ We are leaving few links here:
 
 [Linus]:https://wincent.com/wiki/git_rebase%3A_you're_doing_it_wrong
 
-
-Tags
-------
+## Tags
 
 If you are looking for the source code for a particular release,
 you will find it via **tags**.
 
-* `git tag` will show you list of all tags. 
+* `git tag` will show you list of all tags.
 * Find the tag that corresponds to the release.
 * Use `git checkout <tag-name>` to get this version.
 
@@ -73,31 +69,33 @@ checkout a new branch from this DETACHED HEAD state.
 git checkout -b vors/hotfix
 ```
 
-
-Recommended Git configurations
-==============================
+## Recommended Git configurations
 
 We highly recommend these configurations to help deal with whitespace,
 rebasing, and general use of Git.
 
 > Auto-corrects your command when it's sure (`stats` to `status`)
+
 ```sh
 git config --global help.autoCorrect -1
 ```
 
 > Refuses to merge when pulling, and only pushes to branch with same name.
+
 ```sh
 git config --global pull.ff only
 git config --global push.default current
 ```
 
 > Shows shorter commit hashes and always shows reference names in the log.
+
 ```sh
 git config --global log.abbrevCommit true
 git config --global log.decorate short
 ```
 
 > Ignores whitespace changes and uses more information when merging.
+
 ```sh
 git config --global apply.ignoreWhitespace change
 git config --global rerere.enabled true