Add guidance for repo owners

Documentation/sourcebuild-in-repos/README.md

@@ -0,0 +1,10 @@
+# Repo owner's handbook for source-build
+
+These docs aim to be a collection of useful information for repo owners who work with and participate in source-build.
+
+## Index
+
+[Adding new dependencies](new-dependencies.md)
+[Updating dependencies](update-dependencies.md)
+[Considerations when adding features](adding-features.md)
+[General notes on the source-build build](build-info.md)

Documentation/sourcebuild-in-repos/adding-features.md

@@ -0,0 +1,15 @@
+# New features
+
+New features are great! They also have source-build considerations though. .NET is no longer just multi-platform but also multi-distribution: there's a Linux SDK produced by Microsoft, but there's also a Linux SDK produced by Red Hat, one produced by Fedora, and one that anyone in the community can build himself from source.
+
+## Things to consider
+
+New features, or expansions of current features, should act sensibly across Windows, Linux, and OSX. This also involves taking into account the limitations and conventions of the different platforms - for instance, on Linux, it's typical for the .NET SDK to be installed by root and therefore be unchangeable by normal users, so installing global tools needs to take into account the fact that the user might not be able to add anything to the SDK directories.
+
+XXX details on the global tools issues
+
+New features also need to be compatible across all distributions of .NET - for instance, Fedora and Debian cannot distribute *any* non-open-source code, even samples, tests, or minor additions to licenses like restricting the field that the code can be used in. This includes any code or packages that are used to build product code as well.
+
+XXX fill in the details on dotnet-check/dotnet-format here
+
+XXX Should we create a Github group for source-build community members that would be interested in reviewing things like this?

Documentation/sourcebuild-in-repos/build-info.md

@@ -0,0 +1,13 @@
+# Source-build build info
+
+This is a collection of notes about how source-build can differ in general from your repo's build and what kind of issues that can create. 
+
+## Single-version and single-RID build
+
+Source-build is required to build on a single machine with no internet access. This means that we build targeting a single RID, usually the non-portable RID for the build machines (like rhel.7-x64). We do support building portable (linux-x64) as well - this is useful for bootstrapping new distributions.
+
+We also only build one version of each repo. This means that if your repo turns production of some packages on and off, for instance, if you only produce packages if they are changed, source-build will need a workaround to force all packages to be produced. Additionally, we can only supply one version of each package to a repo. This is injected into the `$(<PackageName>PackageVersion)` variables. The exception is reference-only packages - dotnet/source-build-reference-packages produces multiple versions and these can be hard-coded or use a `$(<PackageName>ReferenceVersion)` property or similar if you don't need source-build to change them.
+
+## No Windows-specific packages
+
+Packages that require Windows components or references cannot be built in source-build. These should use `<ExcludeFromSourceBuild>true</ExcludeFromSourceBuild>` or other options to be excluded from the source-build.

Documentation/sourcebuild-in-repos/new-dependencies.md

@@ -0,0 +1,33 @@
+# Adding a new dependency
+
+## Basics
+When adding a new dependency, there are a few steps common between any type of dependency. If you use darc, `darc add-dependency` will take care of this process for you. Otherwise:
+1. Add the package and a default version to eng/Versions.props. The default version property should be named `<PackageName>PackageVersion`, e.g. `SystemCollectionsImmutablePackageVersion`.
+2. Add the package and a repo reference to eng/Version.Details.xml.
+3. Set up dependency flow from the foreign repo to your repo.
+
+In general, you should aim to use one version of each package. If you are using a package as reference-only, it is possible to use multiple versions, but only one implementation version of each package will be used - source-build will override it to the version that is being built in this version of the SDK.
+
+## Deciding what version to use
+- If you are using the package as reference-only and want the version to be pinned, use a literal version number in the csprojs that reference the project. You can also set up a reference-only package version variable in eng/Versions.props, for instance `<PackageNameReferenceOnly>1.2.3</PackageNameReferenceOnly>` in addition to `<PackageNamePackageVersion>4.5.6</PackageNamePackageVersion>`. Also verify that the package is available in source-build-reference-packages, and if not, contact the source-build team.
+- If you are using the package in the actual build or want the version to be updated whenever the foreign repo publishes to your channel, use the version number property set up in eng/Versions.props. This will be overridden in some cases by source-build.
+- If you are using an external or non-Arcade package, please coordinate as much as possible with other teams using that package. Each package-version is essentially maintained as a separate concern, so something like repo A requiring Newtonsoft.Json 9.0.1 and repo B requiring 12.0.2 essentially doubles the source-build team's work.
+
+## Internal dependencies
+Adding a new dotnet dependency is usually pretty straightforward but does have some edge cases. Use this checklist:
+1. Are you already using a package from the same repo?
+1. This is the simplest case. You can add new dependencies from repos you are already using freely.
+2. Is this a Microsoft repo that uses Arcade to build?
+1. Does the foreign repo depend on your repo, directly or indirectly? i.e. would adding the dependency create a cycle?
+1. This isn't necessarily a deal-breaker - it can sometimes be worked around with reference-only packages. Please contact a source-build team member to discuss.
+2. Does the foreign repo publish to BAR?
+1. If not, please contact them to get them publishing to BAR in an appropriate channel.
+3. If neither of these caveats apply you should be in good shape. Follow the instructions under "Basics" above.
+3. Source-build has in the past used Arcade shims to allow non-Arcade repos to build appropriate packages for source-build. Please contact the source-build team to determine if this is a workable approach for your foreign repo.
+
+## External dependencies
+
+External (non-Microsoft or even non-dotnet) dependencies need to be carefully considered for source-build in addition to the licensing issues you are probably already familiar with.
+1. Microsoft but non-dotnet repos should usually be able to use the same Arcade wrapper to publish appropriate packages for source-build - please contact a source-build team member to discuss.
+2. Dependencies that have no code (e.g. SDKs with just props and targets) can usually be added using the source-build text-only-package process. Contact a source-build team member for more information.
+3. We build some external dependencies in the dotnet/source-build repo. Good targets for this generally have very few if any dependencies and very simple build processes. Contact a source-build team member for more information.

Documentation/sourcebuild-in-repos/update-dependencies.md

@@ -0,0 +1,23 @@
+# Updating a dependency
+
+In most cases, dependency flow should automatically update the packages you depend on. There are some special considerations and things to keep in mind when doing manual updates.
+
+## External packages
+
+Updating a non-Microsoft or non-Arcade package is typically equivalent to adding the new version all over again. Please contact a source-build team member to discuss this.
+
+## Internal packages
+
+If you are manually updating a package, please make sure it's from a compatible branch (e.g. runtime release/6.0 to sdk release/6.0.1xx, release/6.0.2xx, etc). Package versions that you are updating to should be source-built in their respective repos. If the version you need is produced in a branch that is not yet source-build-compatible please let the source-build team know.
+
+## Splitting, combining, and moving packages
+
+These operations often end up causing source-build issues. A typical case of what can happen is
+1. Package A is produced in version 1.
+2. In version 2, Package A is split into Package A1 and Package A2.
+3. A downstream repo is never updated to take the split packages.
+4. The version 2 source-build succeeds because Package A exists in the previously-source-built archive, but no new version of Package A is produced.
+5. Source-build version 3 fails because Package A no longer exists in the previously-source-built archive either.
+
+
+So please keep in mind consumers of your packages and try to keep them informed of these kinds of changes. If you are the consuming repo, consider tracking PRs in the repos that produce your dependencies.