Document issues with using * in AssemblyVersion (dotnet#9892)

Author: tmat

xml/System.Reflection/AssemblyVersionAttribute.xml

@@ -86,12 +86,30 @@
   
 > [!IMPORTANT]
 >  All components of the version must be integers greater than or equal to 0. Metadata restricts the major, minor, build, and revision components for an assembly to a maximum value of <xref:System.UInt16.MaxValue?displayProperty=nameWithType> - 1. If a component exceeds this value, a compilation error occurs.  
-  
- You can specify all the values or you can accept the default build number, revision number, or both by using an asterisk (\*). For example, `[assembly:AssemblyVersion("2.3.25.1")]` indicates 2 as the major version, 3 as the minor version, 25 as the build number, and 1 as the revision number. A version number such as `[assembly:AssemblyVersion("1.2.*")]` specifies 1 as the major version, 2 as the minor version, and accepts the default build and revision numbers. A version number such as `[assembly:AssemblyVersion("1.2.15.*")]` specifies 1 as the major version, 2 as the minor version, 15 as the build number, and accepts the default revision number. The default build number increments daily. The default revision number is the number of seconds since midnight local time (without taking into account time zone adjustments for daylight saving time), divided by 2.  
-  
-> [!NOTE]
->  If you specify an asterisk for the build number, you cannot specify a revision number.  
-  
+
+ For example, `[assembly:AssemblyVersion("2.3.25.1")]` indicates 2 as the major version, 3 as the minor version, 25 as the build number, and 1 as the revision number. 
+
+The <xref:System.Reflection.AssemblyVersionAttribute> attribute allows you to specify an asterisk (\*) in place of the build or revision number. A version number such as `[assembly:AssemblyVersion("1.2.*")]` specifies 1 as the major version and 2 as the minor version, and accepts the default build and revision numbers. A version number such as `[assembly:AssemblyVersion("1.2.15.*")]` specifies 1 as the major version, 2 as the minor version, and 15 as the build number, and accepts the default revision number. The default build number increments daily. The default revision number is the number of seconds since midnight local time (without taking into account time zone adjustments for daylight saving time), divided by 2. If you specify an asterisk for the build number, you can't specify a revision number.  
+
+> [!IMPORTANT] 
+> Use of the <xref:System.Reflection.AssemblyVersionAttribute> attribute that specifies an asterisk:
+>
+> - Makes the build outputs non-reproducible (see [Reproducible builds](https://reproducible-builds.org/)). If the project sets `Deterministic` build property to `true` an error `CS8357` is reported by the compiler.
+> - Might degrade build performance, as it prevents build from caching compiler outputs.
+> - Is incompatible with the [Edit & Continue](/visualstudio/debugger/edit-and-continue-visual-csharp) and [Hot Reload](/visualstudio/debugger/hot-reload) features.
+        
+You can mitigate some of these issues by limiting the use of time-based versions to release builds using conditional compilation, like so:
+
+```
+#if DEBUG
+[assembly: AssemblyVersion("1.0.0.0")]
+#else
+[assembly: AssemblyVersion("1.0.*")]
+#endif
+```
+
+ A better approach to versioning is to derive the assembly or file version from the `HEAD` commit SHA (for git repositories). See, for example, [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning).
+
  The assembly major and minor versions are used as the type library version number when the assembly is exported. Some COM hosts do not accept type libraries with the version number 0.0. Therefore, if you want to expose an assembly to COM clients, set the assembly version explicitly to 1.0 in the `AssemblyVersionAttribute` page for projects created outside Visual Studio 2005 and with no `AssemblyVersionAttribute` specified. Do this even when the assembly version is 0.0. All projects created in Visual Studio 2005 have a default assembly version of 1.0.*.  
   
  To get the name of an assembly you have loaded, call <xref:System.Reflection.Assembly.GetName%2A> on the assembly to get an <xref:System.Reflection.AssemblyName>, and then get the <xref:System.Reflection.AssemblyName.Version%2A> property. To get the name of an assembly you have not loaded, call <xref:System.Reflection.AssemblyName.GetAssemblyName%2A> from your client application to check the assembly version that your application uses.