Add initial docs from @ericstj and @chcosta

2 files changed, 214 insertions, 0 deletions

diff --git a/Documentation/coding-guidelines/buildingvertical.md b/Documentation/coding-guidelines/buildingvertical.md
new file mode 100644
index 0000000000..c143254a9d
--- /dev/null
+++ b/Documentation/coding-guidelines/buildingvertical.md
@@ -0,0 +1,118 @@
+# Building a Vertical Implementation Details #
+
+**Definitions**
+
+*VerticalTargetGroup*
+
+`VerticalTargetGroup` - We need a property to define the vertical target group, but we don't want to set "TargetGroup" explicitly or we won't be able to build the "" TargetGroups for projects.
+  If `VerticalTargetGroup != ""`, we import buildvertical.targets which will contain our additional targets.
+
+*SupportedGroups*
+
+For each ref project and src project, we define `SupportedGroups`. `SupportedGroups` is a tuple for the supported `TargetGroups` and `OSGroups`.
+
+
+ie
+
+ref\System.Runtime.csproj
+```MSBuild
+<PropertyGroup>
+  <SupportedGroups>
+    netstandard1.7_Windows_NT;
+    netstandard1.7_OSX;
+    netstandard1.7_Linux;
+    netcoreapp1.1_Windows_NT;
+    netcoreapp1.1_OSX;
+    netcoreapp1.1_Linux
+  </SupportedGroups>
+<PropertyGroup>
+```
+
+*Contract Layer*
+
+We have a contract layer (msbuild task).
+
+Inputs:
+
+        SupportedGroups
+        VerticalTargetGroup
+        OSGroup
+Output:
+
+        VerticalTargets (ItemTask)
+            metadata: TargetGroup
+                      OSGroup
+
+Given the supported target and OS groups, and the desired vertical target and OS groups, return the closest supported group or empty metadata items.
+How should we handle determining the target / os groups, fallback groups, etc...?  The simplest solution is to use the NuGet api's for targets.  We can use platforms\runtime.json for os groups, or try to use the already existent os group filtering instead of adding it to the contract layer.
+
+Options:
+
+1. Use NuGet API's
+
+2. Make use of inormation we already have and develop our own resolution algorithm.
+
+The current plan is to use the NuGet API's.  We know that there is an intrinsic problem with the NuGet API's, in that we (CoreFx) define the targets (tfm's), but NuGet contains the data / logic, so anytime we want to create a new tfm, we have to go make an update to NuGet.  This is an existent problem.  For now, it is much simpler to utilize NuGet instead of deriving a second solution.  When we break free of the NuGet dependency and wholly define our tfm graph, then we should utilize that solution for this work.
+
+**Building a vertical implementation steps**
+
+1 - Include all projects, we don't need to build the .builds files for each library, because we only want to build each project at most once for a given vertical.
+
+```MSBuild
+<ItemGroup>
+  <Project Include="**\ref\*proj" />
+  <Project Include="**\src\*proj" />
+</ItemGroup>
+```
+
+2 - Iterate all projects through the contract layer, removing (and logging) any projects which return null metadata (not supported).
+
+3 - Build `OutputPath` is set to drop all binaries into a single folder
+
+Current standard `OutputPath`
+
+```MSBuild
+<OutputPath Condition="'$(OutputPath)'==''">$(BaseOutputPath)$(OSPlatformConfig)/$(MSBuildProjectName)/$(TargetOutputRelPath)$(OutputPathSubfolder)</OutputPath>
+```
+Example: E:\gh\chcosta\corefx\bin/AnyOS.AnyCPU.Debug/System.Buffers/netcoreapp1.1/
+
+Proposed vertical `OutputPath`
+
+```MSBuild
+<OutputPath Condition="'$(OutputPath)'==''">$(BinDir)/$(VerticalTargetGroup)/$(OSPlatformConfig)</OutputPath>
+```
+Example: E:\gh\chcosta\corefx\bin/netcoreapp1.7/AnyOS.AnyCPU.Debug
+
+Traditionally, the output path contains the `TargetGroup` as a part of the path.  The flat structure means we don't have to play games with the `TargetPath` to figure out when, for example, "System.Buffers" ("netstandard1.1") is trying to find the "System.Runtime" reference ("netstandard1.7"), that there is no path for "System.Runtime.dll" containing the "netstandard1.1" target group.
+
+4 - Build all reference assemblies.  The reference assembly projects, which were not trimmed in step 2, are all built.  TBD, should we again use the contract layer during the build to determine the targets for the project, or should we capture that as metadata for the project in step 2?
+
+5 - Build all src assemblies into the "OutputPath". The src assembly projects, which were not trimmed in step 2. are all built.
+
+6 - build packages, TBD
+
+**Building a library**
+
+In addition to the ability to build an entire vertical, we require the ability to build a single library.  This, single library build should utilize context to determine TargetGroup and OSGroup.  ie, If a vertical build completes, and you want to build an individual library, it should use the group values from the vertical build unless you specify otherwise.  If you specify otherwise, then those settings become the new settings.  If no context is available, then the library should be built with a set of commond default values.
+
+When building an individual library, or project, its P2P references must be queried to determine supported configurations for building that refernce and then the best configuration must be chosen.
+
+**Additional issues**
+
+- building specific folders (filter by partition)?
+
+- building / running tests for a vertical
+
+  - building tests against packages
+
+- Official builds?
+
+- CI testing?
+
+- Validation
+
+  - Is it an error condition if any library does not contribute to the latest standard vertical?
+
+  - Is it an error condition if a library does not contribute to any OS group? probably
+
+
diff --git a/Documentation/coding-guidelines/netstandard20-corefx-infra.md b/Documentation/coding-guidelines/netstandard20-corefx-infra.md
new file mode 100644
index 0000000000..dbe847f534
--- /dev/null
+++ b/Documentation/coding-guidelines/netstandard20-corefx-infra.md
@@ -0,0 +1,96 @@
+##dotnet/CoreFx
+###Libraries in NETStandard
+- ref
+  - Default targetgroup should be NETCoreApp build
+  - P2P references to other reference assembly CSProjs.
+  - System.Runtime core assembly.
+  - Cross-compiles for concrete frameworks (if different)
+    - EG: exposes types/members not in NETStandard on NETCoreApp, but not on UWP
+- src
+  - Default targetgroup should be NETCoreApp build
+  - depends on System.Runtime?
+    - Yes: P2P to ref CSProjs
+    - No: P2P to implementation projects
+  - **Issue:** what if dependency is not in NETStandard?  EG: Buffers
+    - P2P reference to pkgproj
+    - Reference to NETStandard.dll facade for NETCoreApp
+- pkg
+  - No individual package builds.
+  - We will have a single package for all of NETCore.App's netstandard.library implementation.  Below TBD.
+    - framework split packages
+      - ref\netcoreappN - all refs for NETCoreApp,Version=vN
+    - runtime split packages
+      - runtime\{RID}\lib\netcoreappN - all impl for NETCoreApp,Version=vN, cross-gen'ed for RID
+- tests
+  - By default get all of NETStandard.Library for a specific version that they target (auto-referenced by targets)
+  - Use P2P references to pkgproj for things not in NETStandard.Library
+  - Implementation is automatically injected by targets.
+
+###Libraries above NETStandard
+- ref
+  - Only required if component is inbox somewhere or has multiple implementations for same NETStandard version.
+  - Build against NETStandard.Library package
+  - P2P references to pkgproj for things not in NETStandard.Library
+  - For builds that support older platforms (eg: netstandard1.0-1.6) we'll be building against the older contract-based NETStandard, we will need a story for this for build-from-source.
+- src
+  - Build against NETStandard.Library package
+  - P2P references to pkgproj for things not in NETStandard.Library
+  - For builds that support older platforms (eg: netstandard1.0-1.6) we'll be building against the older contract-based NETStandard, we will need a story for this for build-from-source.
+- pkg
+  - Not in NETCore.App: as today
+  - In NETCore.App: package in NETCore.App package as above
+    - If the library also ships in a package, it will also build a package as today.  This package may or may-not include the same binaries as are used by NETCore.App, for instance if the library builds against older NETStandard versions.
+- tests
+  - By default get all of NETStandard.Library for a specific version that they target (auto-referenced by targets)
+  - Use P2P references for things not in NETStandard.Library
+  - Implementation is automatically injected by targets.
+
+###NETStandard  compatibility facade
+Provides compatibility between NETCore.App and libraries built against NETStandard.
+- ref
+  - Should adapt supported NETStandard.dll to contract reference assemblies.
+  - EG: `GenFacades -contracts:<netstandard.dll> -seeds:<allNetCoreAppReferenceAssemblies>`
+- src
+  - Should adapt supported NETStandard.dll to implementation assemblies.
+  - EG: `GenFacades -contracts:<netstandard.dll> -seeds:<allNetCoreAppImplementationAssemblies>`
+- pkg
+  - No individual package builds.
+  - Should be included in NETCoreApp package as above
+
+###Desktop compatibility facades
+- ref
+  - Should adapt latest desktop surface to contract reference assemblies for anything that has type-overlap with desktop, including assemblies like Microsoft.Win32.Registry which are not in NETStandard.Library.
+  - EG: `GenFacades -contracts:<desktopReferenceAssemblies> -seeds:<allNetCoreAppReferenceAssemblies>`
+- src
+  - Should adapt latest desktop surface to netcore app implementation for anything that has type-overlap with desktop, including assemblies like Microsoft.Win32.Registry which are not in NETStandard.Library.
+  - EG: `GenFacades -contracts:<desktopReferenceAssemblies> -seeds:<allNetCoreAppImplementationAssemblies>`
+- pkg
+  - No individual package builds.
+  - Should be included in NETCoreApp package as above
+
+###Native shims
+- pkg
+  - No individual package builds.
+  - As with libraries in NETStandard the shims will be included in the runtime specific packages for NETCoreApp
+
+##Transition
+
+###End goal
+
+- CoreFx does not build any reference assemblies for NETStandard.
+- For every library in NETStandard.Library, the only configurations in CoreFx are framework-specific.  EG: NETCoreApp1.2, UAP10.1
+- For every library in NETCore.App but not in NETStandard.Library there must be a framework-specific configuration for NETCoreApp1.2.  Other configurations may exist to ship in a package, but those will not be built by folks building just NETCore.App.
+
+###Getting there (WIP)
+
+Folks still consume our current packages so we need to keep building those until we transition.
+
+1. Create a new NETCore.App package: Microsoft.Private.CoreFx.NETCore.App.  This will be an identity package with every ref that targets NETCore.App and runtime-specific packages that have all runtime impl's that apply to NETCore.App.
+2. Filter the content of Microsoft.Private.CoreFx.NETCore.App to just the things that are part of NETCore, and their closure.
+3. Transition tests to use Microsoft.Private.CoreFx.NETCore.App.
+4. Delete packages for things that are only part of Microsoft.Private.CoreFx.NETCore.App and don't ship independently.
+  - Delete configurations for libraries that are no longer used
+  - As packages are deleted we'll need to opt-in to Microsoft.Private.CoreFx.NETCore.App in some way.
+    - proposal:
+      - each CSProj is evaluated for layout path in the context of all of its build configurations.
+      - We'll determine applicability similar to how we do for pkgprojs to idenitify which config to binplace.