Fix Arcade auto-update normalization; explain MICROSOFT_UPSTREAM

.gitattributes

@@ -14,3 +14,28 @@
 # See golang.org/issue/9281.
 
 * -text
+
+# NO MICROSOFT_UPSTREAM:
+# The above lines in this file are the entire content of upstream's
+# ".gitattributes" file. It's important that the development environment in the
+# microsoft/go repo matches upstream's to avoid disrupting work on
+# contributions.
+#
+# The below lines apply autocrlf to a few specific files and folders to make
+# them work nicely with dotnet/arcade's auto-update infrastructure. These
+# files/folders aren't present in upstream.
+#
+# "darc update" is the auto-update command for dotnet/arcade, and it updates
+# file content in a way that ends up with CRLF on Windows and LF on Linux. This
+# can cause thrashing when checked in without autocrlf. We fix this by adding
+# normalization that matches the way Arcade expects it to work:
+# https://github.com/dotnet/arcade/blob/ec35b4879466a6071c16db8fa3ce5d2dca0dfbe8/.gitattributes
+
+/eng/common/** text=auto encoding=UTF-8
+/eng/Version.Details.xml text=auto encoding=UTF-8
+/eng/Versions.props text=auto encoding=UTF-8
+/global.json text=auto encoding=UTF-8
+/NuGet.config text=auto encoding=UTF-8
+
+/eng/common/**/*.sh text eol=lf
+# END NO MICROSOFT_UPSTREAM

eng/README.md

@@ -44,6 +44,10 @@ infrastructure requirements:
 
 * `/*.md` - The Microsoft GitHub organization has standard repository text that
   needs to be in these files, so the upstream Go repo text is changed.
+* `/.gitattributes` - When Arcade auto-update changes files, it uses CRLF or LF
+  depending on runtime/platform. The Go repo disables autocrlf, so this behavior
+  causes thrashing. To fix this, we modified the attributes file to turn
+  autocrlf back on for specific auto-updated files.
 * `/.github` - Contains CI configuration. GitHub requires files to be at this
   absolute path, so the files in the upstream Go repo need to be deleted to
   configure Microsoft's CI.
@@ -53,6 +57,17 @@ infrastructure requirements:
 * `/NuGet.config` - This is a .NET NuGet sources configuration file. This is
   also required at the root of the repo by the Arcade SDK.
 
+To find TODO-style comments describing intentional changes to upstream files
+that seem suitable to contribute, search the repo for:
+
+```
+MICROSOFT_UPSTREAM
+```
+
+You will also find `NO MICROSOFT_UPSTREAM` marking changes that wouldn't be
+useful to contribute to upstream. Typically, changes marked this way have no
+effect whatsoever outside the context of the Microsoft-specific infrastructure.
+
 For a complete list of files that are modified vs. the upstream Git repository,
 first make sure you have the upstream Git refs locally. One way to do this is to
 set up a remote:

eng/_util/cmd/sync/sync.go

@@ -49,6 +49,7 @@ default. This avoids trampling changes in the user's clone.`
 //
 // This is in package scope just so it's easy to find at the top of the file for maintenance.
 var autoResolveOurPaths = []string{
+	".gitattributes",
 	".github",
 	"CODE_OF_CONDUCT.md",
 	"README.md",