From c52c5001cb6873cbf15e2a507ad6dcd84484c1dc Mon Sep 17 00:00:00 2001
From: Andrew Schwartzmeyer <andschwa@microsoft.com>
Date: Wed, 30 Mar 2016 15:13:29 -0700
Subject: [PATCH] Add build instructions matrix to readme

---
 README.md | 55 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index a52d30c980..d88aa5abee 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,18 @@
 PowerShell
 ==========
 
+This repository is "Project Magrathea": Open PowerShell on GitHub, for
+Linux, Windows (.NET Core and Full), and OS X. It is built using the
+[.NET Command Line Interface][dotnet-cli] to support targetting every
+flavor of PowerShell. It is a collaborative effort among many teams:
+
+- Full PowerShell
+- Core PowerShell
+- Open Source Technology Center
+- .NET Foundation
+
+[dotnet-cli]: https://github.com/dotnet/cli
+
 Build Status
 ------------
 
@@ -9,12 +21,31 @@ Build Status
 | Ubuntu 14.04 | [![Build Status](https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master)](https://travis-ci.com/PowerShell/PowerShell) |
 | Windows      | [![Build status](https://ci.appveyor.com/api/projects/status/wb0a0apbn4aiccp1/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/powershell-linux/branch/master) |
 
+Get PowerShell
+--------------
+
+|                       | Linux | Windows .NET Core | Windows .NET Full | OS X |
+|-----------------------|-------|-------------------|-------------------|------|
+| Build from **Source** | [Instructions](docs/building/linux.md) | [Instructions](docs/building/windows-core.md) | [Instructions](docs/building/windows-full.md) | [Instructions](docs/building/osx.md) |
+| Get **Binaries**      | [Releases][] | [Artifacts][] | [Artifacts][] | [Releases][] |
+
+Building summary: `Start-PSBuild` from the module
+`./PowerShellGitHubDev.psm1` (self-host on Linux / OS X)
+
+[releases]: https://github.com/PowerShell/PowerShell/releases
+[artifacts]: https://ci.appveyor.com/project/PowerShell/powershell-linux/build/artifacts
+
 Team coordination
 -----------------
 
 - [PSCore Slack chat](https://pscore.slack.com/)
 - [Waffle.io scrum board](https://waffle.io/PowerShell/PowerShell)
 
+If you encounter any problems, see the [known issues](KNOWNISSUES.md),
+search the [issues][], and if all else fails, open a new issue.
+
+[issues]: https://github.com/PowerShell/PowerShell/issues
+
 ## Obtain the source code
 
 ### Setup Git
@@ -31,27 +62,9 @@ rules, and Git best practices.
 
 Clone this repository. It is a "superproject" and has a number of
 other repositories embedded within it as submodules. *Please* see the
-contributing guidelines and learn about submodules.
-
-```sh
-git clone https://github.com/PowerShell/PowerShell.git
-cd PowerShell
-```
-
-## Building
-
-**The command `dotnet restore` must be done at least once from the top directory
-to obtain all the necessary .NET packages.**
-
-`Start-PSBuild` from module `./PowerShellGitHubDev.psm1` on Windows
-and Linux / OS X, if you are self-hosting PowerShell.
-
-**Tip:** use `Start-PSBuild -Verbose` switch to see more information
-about build process.
-
-If you encounter any problems, see the [known issues](KNOWNISSUES.md),
-otherwise open a new issue on GitHub.
-
+contributing guidelines and learn about submodules. Not every
+submodule is required on every system; see the individual build
+instructions for the necessary subsets.
 
 ## Debugging