Merge PR #786 from knocte/wip/improveReadme

Improve README: docs, rules' categories, contributing...

Author: knocte

.github/workflows/build+test+deploy.yml

@@ -27,8 +27,6 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Restore tools
-      run: dotnet tool restore
     - name: Restore dependencies
       run: dotnet restore
     - name: Build

CONTRIBUTING.md

@@ -11,8 +11,6 @@ Use the issues tracker for:
 * [feature requests](#feature-requests)
 * [submitting pull requests](#pull-requests)
 
-Please **do not** use the issue tracker for personal or commercial support requests.
-
 ## Bug reports
 
 A bug is either a _demonstrable problem_ that is caused by the code in the repository,
@@ -143,3 +141,8 @@ in order to craft an excellent pull request:
    git checkout <your-topic-branch>
    git rebase master
    ```
+
+## Maintaining the project
+
+If you have become a maintainer, please don't forget to follow [the Releasing Guidelines](./RELEASE.md).
+

README.md

@@ -2,9 +2,9 @@
 
 FSharpLint is a static analysis tool for F#. Like many other software linters, it analyzes your source code (using both typed and untyped syntax trees) and highlights any violations of defined F# coding rules. There are various kinds of rules:
 
-* **Conventions:** ensures that your API members follow project- or solution-wide naming conventions.
-* **Smells:** warns about logic that may pose maintainability problems or potential downsides.
-* **Formatting:** checks that code is indented and structured according to specified cosmetic standards.
+* **Conventions:** ensures that your API members follow project- or solution-wide naming standards, or that your source code is structured in parts that don't surpass excessive (and configurable) certain lengths.
+* **Smells:** warns about logic that may indicate defects, or pose maintainability problems or downsides.
+* **Formatting:** checks that code is indented and structured according to specified cosmetic standards (beware, this kind of rules are deprecated in favour of more mature tools such as `fantomas`).
 
 The tool is configurable via JSON and can be run as a console app or as an MSBuild task. It also provides an interface for easy integration into other software.
 
@@ -38,24 +38,19 @@ Package | Version
 ## How to build
 
 1. Make sure you've installed the .NET version defined in [global.json](global.json)
-2. Run `dotnet tool restore` to install all developer tools required to build the project
-3. Run `make` to build (which executes the `Build` target from the FAKE-based [build script](build.fsx))
-4. To run tests use `make check`
-5. To build documentation use `make docs`
+2. Run `make` to build (which executes the `Build` target from the FAKE-based [build script](build.fsx))
+3. To run tests use `make check`
+4. To build documentation use `make docs`
 
 ## How to work with documentation
 
 1. Make sure you've installed the .NET version defined in [global.json](global.json)
 2. Run `dotnet tool restore` to install all developer tools required to build the project
-3. Run `dotnet fsi build.fsx` to build default target of [build script](build.fsx)
-4. Build documentation to make sure everything is fine with `dotnet fsi build.fsx -t Docs`
+3. Run `make` to build the default target of the [build script](build.fsx)
+4. Build documentation to make sure everything is fine with `make docs`
 5. Go to docs folder `cd docs` and start Fornax in watch mode `dotnet fornax watch`
 6. Your documentation should be now accessible on `localhost:8080` and will be regenerated on every file save
 
-## How to release
-
-Please [read the Releasing Guidelines](./RELEASE.md) if you're a maintainer.
-
 ## How to contribute
 
 Bug reports, feature requests, and pull requests are very welcome! Please [read the Contribution Guidelines](./CONTRIBUTING.md)

src/FSharpLint.Core/FSharpLint.Core.fsproj

@@ -44,10 +44,10 @@
     <Compile Include="Rules\Formatting\Spacing\ModuleDeclSpacing.fs" />
     <Compile Include="Rules\Formatting\Spacing\ClassMemberSpacing.fs" />
     <Compile Include="Rules\Formatting\TypedItemSpacing.fs" />
-    <Compile Include="Rules\Formatting\TypePrefixing.fs" />
+    <Compile Include="Rules\Conventions\TypePrefixing.fs" />
     <Compile Include="Rules\Formatting\UnionDefinitionIndentation.fs" />
     <Compile Include="Rules\Conventions\UnneededRecKeyword.fs" />
-    <Compile Include="Rules\Conventions\AsyncExceptionWithoutReturn.fs" />
+    <Compile Include="Rules\Smells\AsyncExceptionWithoutReturn.fs" />
     <Compile Include="Rules\Conventions\FavourStaticEmptyFields.fs" />
     <Compile Include="Rules\Conventions\RecursiveAsyncFunction.fs" />
     <Compile Include="Rules\Conventions\RedundantNewKeyword.fs" />
@@ -58,17 +58,17 @@
     <Compile Include="Rules\Conventions\FavourConsistentThis.fs" />
     <Compile Include="Rules\Conventions\AvoidSinglePipeOperator.fs" />
     <Compile Include="Rules\Conventions\SuggestUseAutoProperty.fs" />
-    <Compile Include="Rules\Conventions\UsedUnderscorePrefixedElements.fs" />
+    <Compile Include="Rules\Smells\UsedUnderscorePrefixedElements.fs" />
     <Compile Include="Rules\Conventions\FavourNonMutablePropertyInitialization.fs" />
     <Compile Include="Rules\Conventions\EnsureTailCallDiagnosticsInRecursiveFunctions.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\RaiseWithTooManyArgumentsHelper.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\FailwithWithSingleArgument.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\RaiseWithSingleArgument.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\NullArgWithSingleArgument.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\InvalidOpWithSingleArgument.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\InvalidArgWithTwoArguments.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\FailwithfWithArgumentsMatchingFormatString.fs" />
-    <Compile Include="Rules\Conventions\RaiseWithTooManyArguments\FailwithBadUsage.fs" />
+    <Compile Include="Rules\Smells\RaiseWithTooManyArguments\RaiseWithTooManyArgumentsHelper.fs" />
+    <Compile Include="Rules\Smells\RaiseWithTooManyArguments\FailwithWithSingleArgument.fs" />
+    <Compile Include="Rules\Smells\RaiseWithTooManyArguments\RaiseWithSingleArgument.fs" />
+    <Compile Include="Rules\Smells\RaiseWithTooManyArguments\NullArgWithSingleArgument.fs" />
+    <Compile Include="Rules\Smells\RaiseWithTooManyArguments\InvalidOpWithSingleArgument.fs" />
+    <Compile Include="Rules\Smells\RaiseWithTooManyArguments\InvalidArgWithTwoArguments.fs" />
+    <Compile Include="Rules\Smells\RaiseWithTooManyArguments\FailwithfWithArgumentsMatchingFormatString.fs" />
+    <Compile Include="Rules\Conventions\FailwithBadUsage.fs" />
     <Compile Include="Rules\Conventions\SourceLength\SourceLengthHelper.fs" />
     <Compile Include="Rules\Conventions\SourceLength\MaxLinesInLambdaFunction.fs" />
     <Compile Include="Rules\Conventions\SourceLength\MaxLinesInMatchLambdaFunction.fs" />
@@ -117,13 +117,13 @@
     <Compile Include="Rules\Conventions\Binding\UselessBinding.fs" />
     <Compile Include="Rules\Conventions\Binding\TupleOfWildcards.fs" />
     <Compile Include="Rules\Conventions\Binding\FavourAsKeyword.fs" />
-    <Compile Include="Rules\Conventions\AvoidTooShortNames.fs" />
-    <Compile Include="Rules\Typography\Indentation.fs" />
-    <Compile Include="Rules\Typography\MaxCharactersOnLine.fs" />
-    <Compile Include="Rules\Typography\TrailingWhitespaceOnLine.fs" />
-    <Compile Include="Rules\Typography\MaxLinesInFile.fs" />
-    <Compile Include="Rules\Typography\TrailingNewLineInFile.fs" />
-    <Compile Include="Rules\Typography\NoTabCharacters.fs" />
+    <Compile Include="Rules\Conventions\Naming\AvoidTooShortNames.fs" />
+    <Compile Include="Rules\Formatting\Typography\Indentation.fs" />
+    <Compile Include="Rules\Formatting\Typography\MaxCharactersOnLine.fs" />
+    <Compile Include="Rules\Formatting\Typography\TrailingWhitespaceOnLine.fs" />
+    <Compile Include="Rules\Conventions\SourceLength\MaxLinesInFile.fs" />
+    <Compile Include="Rules\Formatting\Typography\TrailingNewLineInFile.fs" />
+    <Compile Include="Rules\Formatting\Typography\NoTabCharacters.fs" />
     <Compile Include="Rules\Hints\HintsHelper.fs" />
     <Compile Include="Rules\Hints\HintMatcher.fs" />
     <!-- Application  -->