Add documentation for incremental unsafe warnings

Documentation/README.md

@@ -3,3 +3,4 @@ Documents Index
 
 - [Developer Guide](developer-guide.md)
 - [Intro to .NET Core CLI](intro-to-cli.md)
+- [Addressing Incremental Compilation Warnings](addressing-incremental-compilation-warnings.md)

Documentation/addressing-incremental-compilation-warnings.md

@@ -0,0 +1,17 @@
+Addressing Incremental Compilation Warnings
+===========================================
+
+Incremental compilation is unsafe when compilation relies on tools with potential side effects (tools that can cause data races or modify the state of other projects that have been deemed safe to skip compilation. Or tools that integrate timestamps or guids into the build output).
+
+The presence of such cases will turn off incremental compilation.
+
+Warning codes for project structures that are unsafe:
+
+- __[Pre / Post scripts]__: Scripts that run before and after each compiler invocation can introduce side effects that could cause incremental compilation to output corrupt builds (not building when it should have built) or to over-build. Consider modifying the project structure to run these scripts before / after the entire compile process, not between compiler invocations.
+
+- __[PATH probing]__: Resolving tool names from PATH is problematic. First, we cannot detect when PATH tools change (which would to trigger re-compilation of sources). Second, it adds machine specific dependencies which would cause the build to succeed on some machines and fail on others. Consider using Nuget packages instead of PATH resolved tools. Thus there would be no machine specific dependencies and we would be able track when Nuget packages change and therefore trigger re-compilation. 
+
+- __[Unknown Compiler]__: csc, vbc, and fsc have known side effects (which files and directories they read, write, and what they are not reading/writing).
+We don’t know this for other compilers. So we choose to be safe and disable incremental compilation for now. We are planning to enable specification of tool side effects in a future version, so that they can participate in incremental compilation as well.
+
+- __[Forced Unsafe]__: The build was marked unsafe using the `--force-incremental-unsafe` flag. Remove this flag to enable incremental compilation.

src/Microsoft.DotNet.Tools.Builder/IncrementalPreconditions.cs

@@ -58,7 +58,7 @@ namespace Microsoft.DotNet.Tools.Build
             log.Append(
                 "Incremental compilation will be automatically enabled if the above mentioned project properties are not used. " +
                 "For more information on the properties and how to address them, please consult:\n" +
-                @"https://github.com/cdmihai/cli/wiki/Addressing-Incremental-Compilation-Warnings");
+                @"https://github.com/dotnet/cli/blob/master/Documentation/addressing-incremental-compilation-warnings.md");
 
             log.AppendLine();
             log.AppendLine();