From f91f5ce27e1129f489a4d236937bcbe9ab5cacc1 Mon Sep 17 00:00:00 2001
From: Julie Lenaerts <julielenaerts@gmail.com>
Date: Mon, 4 Nov 2024 17:57:13 +0100
Subject: [PATCH] Add eslint documentation to developers manual

---
 docs/source/development/es-lint.rst | 53 +++++++++++++++++++++++++++++
 docs/source/development/index.rst   |  1 +
 2 files changed, 54 insertions(+)
 create mode 100644 docs/source/development/es-lint.rst

diff --git a/docs/source/development/es-lint.rst b/docs/source/development/es-lint.rst
new file mode 100644
index 000000000..e5d470515
--- /dev/null
+++ b/docs/source/development/es-lint.rst
@@ -0,0 +1,53 @@
+ESLint
+======
+
+To improve the quality of our JS and VueJS code, ESLint and eslint-plugin-vue are implemented within the chill-bundles project.
+
+Commands
+--------
+
+To run ESLint, you can simply use the ``eslint`` command within the chill-bundles directory.
+
+Interesting options are:
+
+- ``--quiet`` to only get errors and silence the warnings
+- ``--fix`` to have ESLint fix what it can, automatically. This will not fix everything.
+
+Rules
+-----
+
+We use Vue 3, so the rules can be configured as follows within the ``eslint.config.mjs`` file:
+
+- ``.configs["flat/base"]`` ... Settings and rules to enable correct ESLint parsing.
+
+Configurations for using Vue.js 3.x:
+
+- ``.configs["flat/essential"]`` : Base rules plus rules to prevent errors or unintended behavior.
+- ``.configs["flat/strongly-recommended"]`` ... Above, plus rules to considerably improve code readability and/or dev experience.
+- ``.configs["flat/recommended"]`` ... Above, plus rules to enforce subjective community defaults to ensure consistency.
+
+Detailed information about which rules each set includes can be found here:
+`https://eslint.vuejs.org/rules/ <https://eslint.vuejs.org/rules/>`_
+
+Manual Rule Configuration
+-------------------------
+
+We can also manually configure certain rules or override rules that are part of the ruleset specified above.
+
+For example, if we want to turn off a certain rule, we can do so as follows:
+
+.. code-block:: javascript
+
+    rules: {
+      'vue/multi-word-component': 'off'
+    }
+
+We could also change the severity of a certain rule from 'error' to 'warning', for example.
+
+Within specific ``.js`` or ``.vue`` files, we can also override a certain rule only for that specific file by adding a comment:
+
+.. code-block:: javascript
+
+    /* eslint multi-word-component: "off", no-child-content: "error"
+    --------
+    Here's a description about why this configuration is necessary. */
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
index d48f92890..d3aefc1b0 100644
--- a/docs/source/development/index.rst
+++ b/docs/source/development/index.rst
@@ -31,6 +31,7 @@ As Chill relies on the `symfony <http://symfony.com>`_ framework, reading the fr
     Exports <exports.rst>
     Embeddable comments <embeddable-comments.rst>
     Run tests <run-tests.rst>
+    ESLint <es-lint.rst>
     Useful snippets <useful-snippets.rst>
     manual/index.rst
     Assets <assets.rst>