Revert "Move config (#125)"

.github/workflows/reviewdog-languagetool.yaml

@@ -0,0 +1,21 @@
+name: Reviewdog LanguageTool
+on: [pull_request]
+jobs:
+  languagetool:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reviewdog/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: github-pr-review
+          level: error
+          language: 'en-US'
+          patterns: '**/*.md **/*.MD **/*.txt **/*.TXT'
+          disabled_categories: ''
+          disabled_rules: 'MORFOLOGIK_RULE_EN_US,EN_UNPAIRED_QUOTES,SENTENCE_WHITESPACE,WHITESPACE_RULE,ARROWS,FILE_EXTENSIONS_CASE'

.github/workflows/reviewdog-misspell.yaml

@@ -0,0 +1,26 @@
+name: Reviewdog Misspell
+on: [pull_request]
+jobs:
+  misspell:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reviewdog/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: github-pr-review
+          level: error
+          locale: "US"
+          pattern: |
+            *.md
+            *.MD
+            *.txt
+            *.TXT
+          filter_mode: nofilter
+          fail_level: none
+          fail_on_error: false

_config.yml

@@ -13,7 +13,6 @@ plugins:
 - jekyll-include-cache
 - jekyll-sitemap
 
-safe: false
 markdown: kramdown
 highlighter: rouge
 kramdown:
@@ -40,7 +39,7 @@ aux_links:
 
 gh_edit_link: true
 gh_edit_link_text: "Edit this page on GitHub."
-gh_edit_repository: "https://github.com/dotnet-project-file-analyzers/dotnet-project-file-analyzers"
+gh_edit_repository: "https://github.com/dotnet-project-file-analyzers/dotnet-project-file-analyzers.github.io"
 gh_edit_branch: "main"
 gh_edit_view_mode: "edit"
 

general/configuration.md

@@ -0,0 +1,86 @@
+---
+nav_order: 1
+---
+
+# Configuration of .NET project file analyzers
+Although all **.NET project file analyzers** should work like a charm,
+there might be reasons to do some adjustments: disabling a specific rule or
+changing its severity. The good news is: this can be done.
+
+## Editor configuration
+Most (but not all) C# and VB.NET rules can be configured in the `.editorconfig`
+file. Unfortunately, changing the severity (and other configuration) of rules
+in the `.editorconfig` is [**NOT** supported by MS Build](https://github.com/dotnet/roslyn/issues/37876).
+
+## Global analyzer config
+It is also possible to configure rules using a [Global AnalyzerConfig](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/configuration-files#global-analyzerconfig)
+`.globalconfig` file located in the same directory as the project file or in
+one of its (grand)parent directories. The following `.globalconfig` file will
+disable rule `Proj0010` and raise `Proj0011` to error level:
+
+``` ini
+is_global = true
+
+dotnet_diagnostic.Proj0010.severity = none  # Define the <OutputType> node explicitly.
+dotnet_diagnostic.Proj0011.severity = error # Property <{0}> has been already defined.
+```
+
+## Analyzer INI file
+It is also possible to define project specific preferences as you would have done in
+an `.globalconfig` file, using `<GlobalAnalyzerConfigFiles>`:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <GlobalAnalyzerConfigFiles Include="../../analyzers-config.ini" />
+  </ItemGroup>
+</Project>
+```
+
+It is recommended to use the `.ini` extension for such a file, as it helps
+with syntax highlighting. A custom config file could look like this:
+
+``` ini
+is_global = false
+
+dotnet_diagnostic.Proj0002.severity = error # Upgrade legacy MS Build project files
+dotnet_diagnostic.Proj0010.severity = none  # Define OutputType explicitly
+```
+
+## Disable rules using <NoWarn>
+It is possible to disable warnings through the `<NoWarn>` tags inside a `<PropertyGroup>`
+tag inside your `.csproj` (or `.props`) file.
+
+An example of disabling rules `Proj0010` and `Proj0011` through the `.csproj` file:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <NoWarn>Proj0010;Proj0011</NoWarn>
+  </PropertyGroup>
+
+</PropertyGroup>
+```
+
+## Suppress specific warnings
+Adopted from C-style languages, it is possible to suppress
+individual violations and/or [false positives](https://en.wikipedia.org/wiki/False_positives_and_false_negatives).
+In a MS Build project file this would look like:
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!-- #pragma warning disable Proj0008 -->
+
+  <ItemGroup>
+    <Folder Include="First" />
+  </ItemGroup>
+
+  <!-- #pragma warning restore Proj0008-->
+
+</Project>
+```
+
+It is worth to point out that the `#pragma warning restore` is optional.

general/nuget-packages.md

@@ -0,0 +1,38 @@
+---
+nav_order: 4
+---
+
+# NuGet packages
+Microsoft provides [best practices](https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices)
+to give NuGet package authors a reference to create and publish high-quality
+packages.
+
+.NET project file analyzers provides rules for most of them:
+
+| Rule                             | Recommendation
+|:--------------------------------:|----------------------------------------------
+| [Proj0200](../rules/Proj0200.md) | Explicitly define the package as packable.
+| [Proj0201](../rules/Proj0201.md) | Consider using SemVer to version your NuGet package.
+| [Proj0202](../rules/Proj0202.md) | Do include a short description (up to 4000 characters) to describe your package.
+| [Proj0203](../rules/Proj0203.md) | Do use the author field for your or your organization's "pretty name."
+| [Proj0204](../rules/Proj0204.md) | Do include several tags with key terms related to your package to enhance discoverability.
+| [Proj0205](../rules/Proj0205.md) | Do include a link to an associated repository
+| [Proj0206](../rules/Proj0206.md) | Do include a link to an associated project or company website.
+| [Proj0207](../rules/Proj0207.md) | Do add a copyright notice to your package with "Copyright (c) <name/company> <year>."
+| [Proj0208](../rules/Proj0208.md) | Do include release notes with each update describing what changes were made.
+| [Proj0209](../rules/Proj0209.md) | Do add a README markdown file that provides an overview of what your package does and how to get started.
+| [Proj0210](../rules/Proj0210.md) | Do include a license expression or license file in your package.
+| [Proj0211](../rules/Proj0211.md) | Do not use the deprecated PackageLicenseUrl to include a license.
+| [Proj0212](../rules/Proj0212.md) | Consider including an icon with your package to help to visually differentiate it. It's a relatively small addition that can improve perception of package quality.
+| [Proj0213](../rules/Proj0213.md) | Consider adding the icon url for maximum compatibility.
+| [Proj0214](../rules/Proj0214.md) | Do include the package id.
+| [Proj0216](../rules/Proj0216.md) | define the product name.
+| *none*                           | Consider choosing a NuGet package name with a prefix that meets NuGet's [prefix reservation criteria](https://learn.microsoft.com/nuget/nuget-org/id-prefix-reservation).
+| [Proj0215](../rules/Proj0215.md) | Do use an image that is 128x128 and has a transparent background (PNG) for the best viewing results.
+|                                  | Consider setting up Source Link to automatically add source control metadata to your NuGet package and make your library easier to debug.
+|                                  | Do choose an open source license to make your package open source.
+| [Proj0243](../rules/Proj0243.md) | Generate a software bill of materials to be compliant with USA legislations.
+| [Proj0244](../rules/Proj0244.md) | Include source code documentation for public API.
+
+## Further reading
+* [learn.microsoft.com/nuget/reference/msbuild-targets](https://learn.microsoft.com/nuget/reference/msbuild-targets)

general/sdk.md

@@ -0,0 +1,53 @@
+---
+nav_order: 2
+---
+
+# .NET Project File Analyzers SDK
+[![DotNetProjectFile.Analyzers.Sdk](https://img.shields.io/nuget/v/DotNetProjectFile.Analyzers.Sdk)![DotNetProjectFile.Analyzers](https://img.shields.io/nuget/dt/DotNetProjectFile.Analyzers.Sdk)](https://www.nuget.org/packages/DotNetProjectFile.Analyzers.Sdk)
+.NET Project File Analyzers ships with its own SDK. This allows files shared by
+multiple projects to be analyzed. It applies a *trick* also used by the
+[Microsoft.NET.Test.Sdk](https://www.nuget.org/packages/Microsoft.NET.Test.Sdk);
+providing both a custom `.props` and a `.targets` MS Build file.
+
+## .net.csproj
+So how does it work? At the root level of your solution (most likely the
+directory containing the [Git](https://en.wikipedia.org/wiki/Git) repo), you
+create a C# Project file with the name `.net.csproj`.
+
+``` xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+   <PackageReference Include="DotNetProjectFile.Analyzers.Sdk" Version="*" PrivateAssets="all" />
+  </ItemGroup>
+
+</Project>
+```
+
+Most files in the directory of this SDK project will be included automatically.
+This includes configuration, text, and markdown files. It will not contain any
+`<Compile>` items unless explicitly added. The SDK project is not intended to
+contain `<Compile>` items, and the binary output is hidden for that reason.
+
+All automatically included files and files added as `<AdditionalFiles>` are
+analyzed by the appropriate .NET Project File Analyzers.
+
+Those analyzers can be included with:
+
+``` xml
+<ItemGroup>
+  <PackageReference Include="DotNetProjectFile.Analyzers" Version="*" PrivateAssets="all" />
+</ItemGroup>
+```
+
+This can be in the `.net.csproj` file, but it is advised to do this in the
+ `Directory.Build.props` file instead.
+
+The SDK project can - on top of the analysis - also act as a replacement of
+the `Solution Items` folder (and other folders) that contain a lot of
+solution files. This should improve the maintainabillity of the `.sln`
+solution too.

general/sonar-integration.md

@@ -0,0 +1,39 @@
+---
+nav_order: 5
+---
+
+# Sonarcloud
+*Currently, this readme is confirmed to work for SonarCloud. The steps in this guide
+might also be relevant for other [SonarSource](https://www.sonarsource.com) products,
+such as SonarQube, but this has not been verified at this time*
+
+[Sonarcloud](https://www.sonarsource.com/products/sonarcloud/) is a service which allows
+you to scan your code for issues, and gives an online dashboard allowing you to see which
+issues exist within the code. This includes any warnings generated by analyzers. In
+addition, it has integration with DevOps platforms (such as [GitHub](https://github.com/)
+and [Azure](https://dev.azure.com/)), which can be set up to automatically add comments
+on pull requests on any new warnings that the change has made, which can help in improving
+code quality.
+
+## The issue with this analyzer and Sonarcloud
+Sonarcloud's analyzer software can run while a build is being made, for example as part
+of a Pull Request check. However, Sonarcloud, by default, does not pick up any warnings
+generated by `.??proj` and `.props` files. This means that any warnings generated by this
+ analyzer will not generate comments on pull requests, nor with they show up in their
+reports, which could result in a situation where they are not noticed and solved by
+developers.
+
+## Sonarcloud integration
+There is currently no *'elegant'* solution to have the warnings show up on SonarCloud,
+however, there is a workaround. By adding the `.??proj` and `.props` files as content,
+SonarCloud will recognize its warnings and pick them up, same as any warnings in the
+code.
+
+For Example:
+``` xml
+  <ItemGroup>
+    <Content Include="*.??proj" CopyToOutputDirectory="Never"/>
+    <Content Include="../../props/common.props" CopyToOutputDirectory="Never" Link="Properties/common.props"/>
+    <Content Include="../../Directory.Packages.props" CopyToOutputDirectory="Never" Link="Properties/Directory.Packages.props"/>
+  </ItemGroup>
+```

navigation/analyzer_rules.md

@@ -0,0 +1,6 @@
+---
+title: Analyzers 
+parent: MSBuild
+ancestor: Rules
+nav_order: 7
+---

navigation/cpm_rules.md

@@ -0,0 +1,6 @@
+---
+title: Central Package Management
+parent: MSBuild
+ancestor: Rules
+nav_order: 6
+---

navigation/editorconfig_rules.md

@@ -0,0 +1,5 @@
+---
+title: Editorconfig 
+parent: Rules
+nav_order: 4
+---

navigation/formatting_rules.md

@@ -0,0 +1,5 @@
+---
+title: Formatting 
+parent: Rules
+nav_order: 200
+---

navigation/general_project_rules.md

@@ -0,0 +1,6 @@
+---
+title: General
+parent: MSBuild
+ancestor: Rules
+nav_order: 10
+---

navigation/generic_rules.md

@@ -0,0 +1,5 @@
+---
+title: Generic 
+parent: Rules
+nav_order: 100
+---

navigation/ini_rules.md

@@ -0,0 +1,5 @@
+---
+title: INI 
+parent: Rules
+nav_order: 3
+---

navigation/licensing.md

@@ -0,0 +1,5 @@
+---
+title: Licensing
+parent: Rules
+nav_order: 4
+---

navigation/msbuild_rules.md

@@ -0,0 +1,5 @@
+---
+title: MSBuild
+parent: Rules
+nav_order: 1
+---

navigation/other_rules.md

@@ -0,0 +1,6 @@
+---
+title: Other 
+parent: MSBuild
+ancestor: Rules
+nav_order: 9
+---

navigation/packaging_rules.md

@@ -0,0 +1,6 @@
+---
+title: Packaging
+parent: MSBuild
+ancestor: Rules
+nav_order: 2
+---

navigation/publishing_rules.md

@@ -0,0 +1,6 @@
+---
+title: Publishing
+parent: MSBuild
+ancestor: Rules
+nav_order: 3
+---

navigation/resx_rules.md

@@ -0,0 +1,5 @@
+---
+title: Resources 
+parent: Rules
+nav_order: 2
+---

navigation/rules.md

@@ -0,0 +1,4 @@
+---
+title: Rules
+nav_order: 3
+---

navigation/sdk_rules.md

@@ -0,0 +1,6 @@
+---
+title: SDK
+parent: MSBuild
+ancestor: Rules
+nav_order: 5
+---