Add doc about package references, korebuild, and an intro doc

[ci skip]

docs/Intro.md

@@ -0,0 +1,25 @@
+Intro to BuildTools
+------------------
+
+This repo contains console tools, MSBuild tasks, and targets used to build ASP.NET Core.
+This document is a high-level overview of how these build tools work.
+
+## Step-by-step how "build.cmd" works
+
+Most KoreBuild repositories will have an identical build.cmd script in the top-level repo directory. This script can be found in [scripts/bootstrapper/build.cmd][build-cmd]. These are the steps the script takes. (The same steps apply to build.sh for Linux builds.)
+
+1. [build.cmd][build-cmd] invokes "[run.ps1][run-ps1] default-build".
+1. [run.ps1][run-ps1] downloads and extracts KoreBuild as a zip file
+1. [run.ps1][run-ps1] imports the [KoreBuild.psm1][korebuild-psm1] file which contains a few functions for invoking commands. It then invokes `Invoke-KoreBuildCommand 'default-build'`
+1. [KoreBuild.psm1][korebuild-psm1] defines the `Invoke-KoreBuildCommand` function. This function will
+    1. Ensure dotnet is installed
+    1. Build `$RepoRoot/build/tasks/RepoTasks.csproj` if it exists
+    1. Starts MSBuild by calling `dotnet msbuild KoreBuild.proj`
+1. [KoreBuild.proj][korebuild-proj] is the entry point for building the entire repo in an MSBuild process. By default, this project will restore, compile, package, and test \*.sln files. It has some extensibility points to repos can extend. See [./KoreBuild.md](./KoreBuild.md).
+
+
+[build-cmd]: ../scripts/bootstrapper/build.cmd
+[run-ps1]: ../scripts/bootstrapper/run.ps1
+[korebuild-psm1]: ../files/KoreBuild/scripts/KoreBuild.psm1
+[korebuild-proj]: ../files/KoreBuild/KoreBuild.proj
+[korebuild-common]: ../files/KoreBuild/KoreBuild.proj

docs/KoreBuild.md

@@ -0,0 +1,100 @@
+KoreBuild
+=========
+
+KoreBuild is a set of MSBuild targets and tasks used to define a common set of build and test tasks. The entry point for KoreBuild is defined in [KoreBuild.proj][korebuild-proj].
+
+## KoreBuild Lifecycle
+
+The KoreBuild chains together these targets in this order. Custom targets can chain off these.
+
+1. Prepare - pre-build actions like making directories
+1. Restore - NuGet restore
+1. Compile - calls /t:Build on \*.sln files
+1. Package - NuGet pack and other packaging steps
+1. Test - invokes VSTest
+1. Verify - post build tests
+
+When not specified, the default target is `/t:Build`, which runs all of these lifecycle targets.
+
+## Other common targets
+
+These targets are also available, but are not run in the default lifecycle.
+
+- Clean - cleans artifacts, executes /t:Clean on solutions
+- Rebuild - executes /t:Rebuild on solutions
+- Resx - generates resx files
+- Noop - a target that does nothing
+- Publish - pushes artifacts to NuGet feeds and blob stores
+
+## Extensibility points
+
+### Modules
+
+KoreBuild is designed to be a modular system. It is written as a backbone of default lifecycle targets and imports.
+Default functionality, such as building solutions and testing with VSTest, are written as modules in `files/KoreBuild/modules`.
+
+Other default functionality that require tasks are built from `modules/` in this repo.
+These include tasks for downloading NuGet packages, creating Zip files, retrieving Git information, and more.
+
+Additional KoreBuild modules can be imported by setting `CustomKoreBuildModulesPath` as a property or environment variable.
+Anything matching `$(CustomKoreBuildModulesPath)/*/module.props` and `$(CustomKoreBuildModulesPath)/*/modules.targets` will be imported into KoreBuild.
+
+### RepoTasks
+
+RepoTasks is a C# project that can be used to define MSBuild tasks that apply only to a specific repository.
+
+```
+build/tasks/RepoTasks.csproj
+```
+
+If this file exists, KoreBuild will restore and publish it to build/tasks/bin/publish/
+
+```
+build/tasks/RepoTasks.tasks
+```
+
+If this file exists, KoreBuild will import it.
+
+Sample contents:
+```xml
+<!-- build/tasks/RepoTasks.tasks -->
+
+<Project>
+  <UsingTask TaskName="RepoTasks.MyCustomTask" AssemblyFile="$(MSBuildThisFileDirectory)bin\publish\RepoTasks.dll" />
+</Project>
+```
+
+
+### repo.props
+```
+<root>/build/repo.props
+```
+
+If this file exists, it is imported shortly after [KoreBuild.Common.props][../files/KoreBUild/KoreBuild.Common.props].
+
+>**Best practies**: Only define properties and settings in \*.props files.
+
+### repo.targets
+
+```
+<root>/build/repo.targets
+```
+
+If this file exists, it is imported shortly after [KoreBuild.Common.targets][../files/KoreBUild/KoreBuild.Common.targets].
+
+>**Best practies**: Define custom build steps in \*.targets files.
+
+
+### version.props
+
+```
+<root>/version.props
+```
+
+If this file exists, it is imported shortly after [KoreBuild.Common.props][../files/KoreBUild/KoreBuild.Common.props]. It should contain settings like VerisonPrefix, PackageVersion, VerisonSuffix, and others.
+
+These values can be used to ensure that all NuGet packages produced have the same version.
+
+>**Best practies**: This file should contain all settings related to asset versions.
+
+[korebuild-proj]: ../files/KoreBuild/KoreBuild.proj

docs/PackageReferenceManagement.md

@@ -0,0 +1,80 @@
+PackageReference management
+---------------------------
+
+## Usage
+
+KoreBuild includes tools to help you automatically update your `dependencies.props` files.
+
+#### Generating a dependencies.props file
+
+On an existing project, you can execute the following command:
+```
+run.ps1 generate deps
+```
+
+This will update csproj files and overwrite your build/dependencies.props file with variables.
+
+#### Updating dependencies.props
+
+KoreBuild can help you automatically update the `build/dependencies.props` file in your repo by using a lineup package.
+
+On command line, you can then execute
+```
+run.ps1 upgrade deps
+```
+
+This command requires you set a few properties so the command can download a remote package and use that as the source
+of version information. Most aspnetcore repos will set this in `build/repo.props`
+
+```xml
+<PropertyGroup>
+  <LineupPackageId>Internal.AspNetCore.Universe.Lineup</LineupPackageId>
+  <!-- Optional, and can float -->
+  <LineupPackageVersion>2.1.0-*</LineupPackageVersion>
+  <LineupPackageRestoreSource>https://dotnet.myget.org/F/aspnetcore-dev/api/v3/index.json</LineupPackageRestoreSource>
+</PropertyGroup>
+```
+
+The lineup package itself contains a file that lists all version, and is itself also packaged under `build/dependencies.props`. The `upgrade deps` command will update any matching variables from the lineup package in the local copy of build/dependencies.props.
+
+## Restrictions on PackageReference usage
+
+To manage the complexity of keeping PackageReference versions consistent within a repo and between multiple repos, KoreBuild will enforce the following patterns for using PackageReference.
+
+#### 1. build/dependencies.props
+
+Each repository should have this file, and it should look like this.
+
+```xml
+<Project>
+  <PropertyGroup>
+    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
+  </PropertyGroup>
+  <PropertyGroup Label="Package Versions">
+    <NewtonsoftJsonPackageVersion>10.0.1</NewtonsoftJsonPackageVersion>
+    <MicrosoftNETTestSdkPackageVersion>15.3.0</MicrosoftNETTestSdkPackageVersion>
+    <MoqPackageVersion>4.7.49</MoqPackageVersion>
+    <XunitPackageVersion>2.3.0</XunitPackageVersion>
+  </PropertyGroup>
+  <Import Project="$(DotNetPackageVersionPropsPath)" Condition=" '$(DotNetPackageVersionPropsPath)' != '' " />
+</Project>
+```
+
+### 2. PackageReference's should use variables to set versions
+
+All .csproj files should set the version of a package reference like this:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Newtonsoft.Json" Version="$(NewtonsoftJsonPackageVersion)" />
+</ItemGroup>
+```
+
+#### Opt-out of restrictions
+
+To opt-out of these restrictions, projects should add this to the `build/repo.props` file in their repository.
+```xml
+<PropertyGroup>
+  <DisablePackageReferenceRestrictions>true</DisablePackageReferenceRestrictions>
+</PropertyGroup>
+```