Merge pull request #6303 from jmarolf/publish-readme

Add readme for Microsoft.CodeAnalysis.NetAnalyzers package
dotnet · Dec 8, 2022 · 3bc91ee · 3bc91ee
2 parents 2928b85 + d7abfa7
commit 3bc91ee
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 18 deletions.
diff --git a/eng/GenerateAnalyzerNuspec.targets b/eng/GenerateAnalyzerNuspec.targets
@@ -154,8 +154,11 @@
       <_NuspecMetadata Include="repositoryType=$(RepositoryType)" />
       <_NuspecMetadata Include="repositoryCommit=$(SourceRevisionId)" />
       <_NuspecMetadata Include="repositoryUrl=$(PrivateRepositoryUrl)" />
+      <_NuspecMetadata Include="readme=$(PackageReadmeFile)" />
     </ItemGroup>
 
-    <Exec Command='"$(DotNetExecutable)" --roll-forward major "$(_GenerateAnalyzerNuspecPath)" "$(NuspecFile)" "$(AssetsDir)$(EscapeDirectorySuffix)" "$(MSBuildProjectDirectory)" "$(Configuration)" "$(TargetFrameworksForPackage)" "@(_NuspecMetadata)" "@(AnalyzerNupkgFile)" "@(AnalyzerNupkgFolder)" "@(AnalyzerNupkgAssembly)" "@(AnalyzerNupkgDependency)" "@(AnalyzerNupkgLibrary)" "$(_GeneratedRulesetsDir)" "$(_GeneratedEditorconfigsDir)" "$(ArtifactsBinDir)$(EscapeDirectorySuffix)" "$(AnalyzerDocumentationFileDir)" "$(AnalyzerDocumentationFileName)" "$(AnalyzerSarifFileDir)" "$(AnalyzerSarifFileName)" "$(AnalyzerConfigurationFileDir)" "$(AnalyzerConfigurationFileName)" "$(_GeneratedGlobalAnalyzerConfigsDir)"' />
+    <Error Text="Multiple readme files specified for this package." Condition="@(PackageReadmeFileSource->Count()) > 1" />
+
+    <Exec Command='"$(DotNetExecutable)" --roll-forward major "$(_GenerateAnalyzerNuspecPath)" "$(NuspecFile)" "$(AssetsDir)$(EscapeDirectorySuffix)" "$(MSBuildProjectDirectory)" "$(Configuration)" "$(TargetFrameworksForPackage)" "@(_NuspecMetadata)" "@(AnalyzerNupkgFile)" "@(PackageReadmeFileSource)" "@(AnalyzerNupkgFolder)" "@(AnalyzerNupkgAssembly)" "@(AnalyzerNupkgDependency)" "@(AnalyzerNupkgLibrary)" "$(_GeneratedRulesetsDir)" "$(_GeneratedEditorconfigsDir)" "$(ArtifactsBinDir)$(EscapeDirectorySuffix)" "$(AnalyzerDocumentationFileDir)" "$(AnalyzerDocumentationFileName)" "$(AnalyzerSarifFileDir)" "$(AnalyzerSarifFileName)" "$(AnalyzerConfigurationFileDir)" "$(AnalyzerConfigurationFileName)" "$(_GeneratedGlobalAnalyzerConfigsDir)"' />
   </Target>
 </Project>
diff --git a/nuget/NetAnalyzers/Microsoft.CodeAnalysis.NetAnalyzers.Package.csproj b/nuget/NetAnalyzers/Microsoft.CodeAnalysis.NetAnalyzers.Package.csproj
@@ -13,6 +13,7 @@
     <ContainsPortedFxCopRules>true</ContainsPortedFxCopRules>
 	  <AnalyzerDocumentationFileDir>$(RepoRoot)src\NetAnalyzers</AnalyzerDocumentationFileDir>
     <AnalyzerSarifFileDir>$(RepoRoot)src\NetAnalyzers</AnalyzerSarifFileDir>
+    <PackageReadmeFile>documentation\readme.md</PackageReadmeFile>
     <IsShippingPackage>true</IsShippingPackage>
 
     <!-- Override the version prefix and label for NetAnalyzers projects -->
@@ -24,6 +25,7 @@
     <AnalyzerNupkgAssembly Include="Microsoft.CodeAnalysis.NetAnalyzers.dll" />
     <AnalyzerNupkgAssembly Include="Microsoft.CodeAnalysis.CSharp.NetAnalyzers.dll" />
     <AnalyzerNupkgAssembly Include="Microsoft.CodeAnalysis.VisualBasic.NetAnalyzers.dll" />
+    <PackageReadmeFileSource Include="..\..\src\NetAnalyzers\readme.md"/>
 	</ItemGroup>
 
   <ItemGroup>

diff --git a/src/NetAnalyzers/readme.md b/src/NetAnalyzers/readme.md
@@ -0,0 +1,21 @@
+# Microsoft.CodeAnalysis.NetAnalyzers
+
+Contains all **the .NET code analysis rules (CAxxxx)** that are built into the .NET SDK starting .NET5 release. The documentation for CA rules can be found at [docs.microsoft.com/visualstudio/code-quality/code-analysis-for-managed-code-warnings](https://learn.microsoft.com/visualstudio/code-quality/code-analysis-for-managed-code-warnings).
+
+You do not need to manually install this NuGet package to your project if you are using .NET5 SDK or later. These analyzers are enabled by default for projects targeting .NET5 or later. For projects targeting earlier .NET frameworks, you can enable them in your MSBuild project file by setting one of the following properties:
+
+1. *EnableNETAnalyzers*
+
+   ```xml
+   <PropertyGroup>
+     <EnableNETAnalyzers>true</EnableNETAnalyzers>
+   </PropertyGroup>
+   ```
+
+2. *AnalysisLevel*
+
+   ```xml
+   <PropertyGroup>
+     <AnalysisLevel>latest</AnalysisLevel>
+   </PropertyGroup>
+   ```
diff --git a/src/Tools/GenerateAnalyzerNuspec/Program.cs b/src/Tools/GenerateAnalyzerNuspec/Program.cs
@@ -13,20 +13,21 @@
 string[] tfms = args[4].Split(';');
 var metadataList = args[5].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
 var fileList = args[6].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
-var folderList = args[7].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
-var assemblyList = args[8].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
-var dependencyList = args[9].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
-var libraryList = args[10].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
-var rulesetsDir = args[11];
-var editorconfigsDir = args[12];
-var artifactsBinDir = args[13];
-var analyzerDocumentationFileDir = args[14];
-var analyzerDocumentationFileName = args[15];
-var analyzerSarifFileDir = args[16];
-var analyzerSarifFileName = args[17];
-var analyzerConfigurationFileDir = args[18];
-var analyzerConfigurationFileName = args[19];
-var globalAnalyzerConfigsDir = args[20];
+var readmeFile = args[7];
+var folderList = args[8].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
+var assemblyList = args[9].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
+var dependencyList = args[10].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
+var libraryList = args[11].Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
+var rulesetsDir = args[12];
+var editorconfigsDir = args[13];
+var artifactsBinDir = args[14];
+var analyzerDocumentationFileDir = args[15];
+var analyzerDocumentationFileName = args[16];
+var analyzerSarifFileDir = args[17];
+var analyzerSarifFileName = args[18];
+var analyzerConfigurationFileDir = args[19];
+var analyzerConfigurationFileName = args[20];
+var globalAnalyzerConfigsDir = args[21];
 
 var result = new StringBuilder();
 
@@ -38,6 +39,7 @@
 string repositoryType = string.Empty;
 string repositoryUrl = string.Empty;
 string repositoryCommit = string.Empty;
+string readmePackageLocation = string.Empty;
 
 foreach (string entry in metadataList)
 {
@@ -50,6 +52,7 @@
         case "repositoryUrl": repositoryUrl = value; continue;
         case "repositoryCommit": repositoryCommit = value; continue;
         case "license": result.AppendLine($"    <license type=\"expression\">{value}</license>"); continue;
+        case "readme": readmePackageLocation = value; break;
     }
 
     if (value.Length > 0)
@@ -87,7 +90,7 @@
 result.AppendLine(@"  <files>");
 result.AppendLine(@"    $CommonFileElements$");
 
-if (fileList.Length > 0 || assemblyList.Length > 0 || libraryList.Length > 0 || folderList.Length > 0)
+if (fileList.Length > 0 || assemblyList.Length > 0 || libraryList.Length > 0 || folderList.Length > 0 || readmePackageLocation.Length > 0)
 {
     const string csName = "CSharp";
     const string vbName = "VisualBasic";
@@ -133,7 +136,7 @@
         foreach (var tfm in tfms)
         {
             string assemblyFolder = Path.Combine(artifactsBinDir, assemblyNameWithoutExtension, configuration, tfm);
-            string assemblyPathForNuspec = Path.Combine(assemblyNameWithoutExtension, configuration, tfm, assembly);
+            string assemblyPathForNuspec = Path.Combine(assemblyFolder, assembly);
 
             foreach (string target in targets)
             {
@@ -148,7 +151,7 @@
                         if (File.Exists(resourceAssemblyFullPath))
                         {
                             var directoryName = Path.GetFileName(directory);
-                            string resourceAssemblyPathForNuspec = Path.Combine(assemblyNameWithoutExtension, configuration, tfm, directoryName, resourceAssemblyName);
+                            string resourceAssemblyPathForNuspec = Path.Combine(artifactsBinDir, assemblyNameWithoutExtension, configuration, tfm, directoryName, resourceAssemblyName);
                             string targetForNuspec = Path.Combine(target, directoryName);
                             result.AppendLine(FileElement(resourceAssemblyPathForNuspec, targetForNuspec));
                         }
@@ -164,6 +167,13 @@
         result.AppendLine(FileElement(fileWithPath, "build"));
     }
 
+    if (readmePackageLocation.Length > 0)
+    {
+        readmeFile = Path.IsPathRooted(readmeFile) ? readmeFile : Path.GetFullPath(Path.Combine(projectDir, readmeFile));
+        var directoryName = Path.GetDirectoryName(readmePackageLocation) ?? string.Empty;
+        result.AppendLine(FileElement(readmeFile, directoryName));
+    }
+
     foreach (string file in libraryList)
     {
         foreach (var tfm in tfms)