Remove the rules from the README, and write why there are no built-in…

… rules
jfmengels · Aug 22, 2019 · c1562aa · c1562aa
1 parent 9463d89
commit c1562aa
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -55,28 +55,14 @@ You can get started with an empty configuration with the command line tool by ru
 reading the rest of this document, but especially the section on
 [when to enable a rule in your configuration](#when-to-write-or-enable-a-rule).
 
-## Rules
-
-These are the rules that are built-in and available for you to choose from.
-
-- **NoDebug** - Forbid the use of `Debug` before it goes into production.
-- **NoExtraBooleanComparison** - Forbid extraneous comparisons with booleans, like `(isAdmin user) == True`.
-- **NoImportingEverything** - Forbid importing everything from your module. This can especially be confusing to newcomers when the exposed functions and types are unknown to them.
-- **NoUnusedVariables** - Reports variables that are declared but never used.
-- **NoUnusedTypeConstructors** - Reports type constructors that are declared but never used.
-
-The following is a list of rules that were temporarily removed when changing the AST implementation, and which can potentially be re-added later.
-- **NoExposingEverything** - Forbid exporting everything in your modules `module Main exposing (..)`, to make your module explicit in what it exposes.
-- **NoConstantCondition** - Forbid the use of expressions in an If condition whose value are always the same.
-- **NoNestedLet** - Forbid nesting let expressions directly.
-- **NoUnannotatedFunction** - Ensure every top-level function declaration has a type annotation.
-- **NoUselessIf** - Reports when both paths of an If expression result will lead to the same value.
-- **NoUselessPatternMatching** - Reports case expressions that can be simplified. Either when all patterns will lead to the same value, or when a pattern will lead to the same value as the default pattern.
-- **NoWarningComments** - Detect comments containing words like `TODO`, `FIXME` and `XXX`.
-- **SimplifyPiping** - Simplify piped functions like `List.map f >> List.map g` to `List.map (f >> g)`
-- **SimplifyPropertyAccess** - Replace functions that only return the property of its parameter by an access function, like `(\x -> x.foo)` to `.foo`
-- **ElmTest.NoDuplicateTestBodies** - Forbid having multiple tests with the same bodies. Often a consequence of copy-pasting tests.
+`elm-lint` does not come with any built-in rules. You can read why [here](https://github.com/jfmengels/elm-lint/blob/master/documentation/design/no-built-in-rules.md). You can get rules from packages in the Elm package registry using
+the command line tool `elm-lint install authorName/dependencyName`.
 
+This will add the dependency in your `test-dependencies`, along with your
+[`elm-test`](https://github.com/elm-explorations/test) dependencies.
+
+You can also [write your own rules](#write-your-own-rule), as shown in the next
+section.
 
 ## Write your own rule
 

diff --git a/documentation/design/no-built-in-rules.md b/documentation/design/no-built-in-rules.md
@@ -0,0 +1,35 @@
+# Why no built-in rules
+
+`elm-lint` comes with no rules out of the box. It used to have some, but then I
+decided it was better to have them all extracted into different packages.
+
+The main reason, is that if `elm-lint` had "core" rules, users would think they
+are all best practices. I am of the opinion that in practice, any rule that
+could be written can potentially be unwanted under certain circumstances, and
+can therefore hardly be enforced all the time without more consideration.
+
+`elm-lint` is plenty opinionated, but what counts as best practices in terms of
+which linting configuration is not its concern, it's up to each user to decide
+carefully whether or not to enable it. `elm-lint` will just provide the tools to
+do so.
+
+Maybe some semi-official linting packages will emerge
+
+If there are no core rules, then there are also no technical distinctions
+between then and package rules. They all have access to the same tools, and
+there is no rule that can do more than an other could.
+
+A benefit of this, is that `elm-lint` will not need to have major version
+changes when one of its rules gets updated or removed, because it doesn't have
+one.
+
+The inconvenience, is that if `elm-lint` happens to have a major version, which
+I try to prevent as much as possible, all packages that depend on it (meaning at
+least all packages with linting rules) will need to be updated and re-released,
+similar to what would happen when Elm gets a new (major or minor) version. Since
+Elm doesn't (in practice) allow for duplicate dependencies with different major
+versions, users would not be able to use the next version of `elm-lint` with the
+updated version of each package, until all packages are updated. Or they will
+need to disable the rules from non-updated packages for a while.
+This would happen even if there are built-in rules too, but more work would need
+to be done by the community to bump their packages.