Improve README.md and branch explanation (#2)

* Improve README.md and branch explanation

* Update README.md

Co-authored-by: Julien Couvreur <[email protected]>

* Add line to purpose description: support across Microsoft

Co-authored-by: Julien Couvreur <[email protected]>

README.md

@@ -1,22 +1,14 @@
 # Microsoft Go Infrastructure
 
-The `github.com/microsoft/go-infra` module is a library used by Microsoft to
-build Go from source. The repository also contains other utilities that help
-Microsoft to build and use Go.
+This repository contains libraries and utilities that Microsoft uses to:
 
-## Branches
+* Build Go inside Microsoft infrastructure using up-to-date source code.
+* Build Docker images that contain the Microsoft build of Go.
+* Support the secure use of Go and the Go ecosystem across Microsoft.
 
-This repository has only one maintained branch, `main`, rather than maintaining
-one branch per release.
-
-Using a single branch makes this repository easy to maintain. It also means we
-can use the infra module to share code between the Go release branches without
-as many cherry-picks, only module dependency updates.
-
-The cost of a single branch is that any change to the branch needs to be
-compatible with *all* release branches. This is why some infra must still be
-maintained in the release branches themselves: differences between the branches
-create different infra requirements.
+To build Go from source or download a binary release, visit
+https://golang.org/dl/. This repository is not involved in the official Go
+distribution.
 
 ## Contributing
 

docs/README.md

@@ -0,0 +1,45 @@
+# Microsoft Go Infrastructure
+
+This repository is used by Microsoft to build Go. See the root
+[README.md](../README.md) for the project overview.
+
+## Branches
+
+This repository has only one maintained branch, `main`. This branch contains the
+infrastructure used by Microsoft to build any Go release branch.
+
+This is similar to how all release branches of
+[`go`](https://go.googlesource.com/go/) are built and released using the one
+branch of [`x/build`](https://go.googlesource.com/build/).
+
+Using a single branch has significant tradeoffs. On the plus side:
+
+* :+1: Parts of the infra that *do not* take part in the Go build are intuitive
+  to maintain. We would only use the `main` version of this code anyway, so it
+  makes sense to only have a single branch where the code is maintained.
+  * If this code were in a repository with release branches, every release
+    branch would have **dead code**: a copy of the infra at the point in time
+    that the release branch forked from `main`.
+  * For example: auto-updating the Docker image repo is not part of the Go
+    build. It runs an Azure Pipelines `yml` file in the main branch.
+* :+1: Parts of the infra that *do* take part in the Go build can be shared more
+  easily.
+  * Instead of cherry-picking every `main` commit into every applicable release
+    branch all the time, the `go-infra` module dependency can simply be updated
+    to the latest version to get a batch of fixes.
+
+There are downsides:
+
+* :confused: When making a change to `go-infra`, it can be (very!) hard to tell
+  if the change will break a release branch.
+  * This can be mitigated by setting up PR validation jobs that that simulate an
+    update across each active release branch and run a Go build in each one.
+* :confused: It is more difficult to design changes or new infra features when
+  they must be compatible with every release branch at the same time.
+  * It may be impossible, in some cases. This forces the code to be maintained
+    in the repository rather than `go-infra`.
+
+It's important to consider the balance. This is why not all of the code
+Microsoft uses to build Go is stored in this repo, even if it could be migrated
+(even partially). A significant amount of important Go build and packaging logic
+is stored in the repo where it's used.