[docs] add README best practice (#57)

Co-authored-by: Kristjan ESPERANTO <35647502+KristjanESPERANTO@users.noreply.github.com>

Author: dathbe

guides/README.md

@@ -10,4 +10,24 @@ Please help use to improve this guide. If you have any suggestions, please creat
 
 ## Hint "No ESLint configuration was found. ESLint is very helpful, it is worth using it even for small projects."
 
-To get started with ESLint checkout [ESLint](eslint.md).
+To get started with ESLint, check out [ESLint](eslint.md).
+
+## Hint "Recommendation: The README seems not to have a config example. Please add one."
+
+For information on best practices for a README config section, check out [Config Instructions](readme_bestpractices.md#Config-Instructions).
+
+## Hint "Recommendation: The README seems not to have an install section (like ## Installation). Please add one."
+
+For information on best practices for a README installation section, check out [Installation Instructions](readme_bestpractices.md#Installation-Instructions).
+
+## Hint "Recommendation: The README seems not to have an update section (like ## Update). Please add one."
+
+For information on best practices for a README update section, check out [Update Instructions](readme_bestpractices.md#Update-Instructions).
+
+## Hint "Recommendation: The README seems to have a config example without a trailing comma. Please add one."
+
+For information on best practices for a README config section, check out [Config Instructions](readme_bestpractices.md#Config-Instructions).
+
+## Hint "Recommendation: The README seems to have a modules array (Found modules: [). This is usually not necessary. Please remove it if it is not needed."
+
+For information on best practices for a README config section, check out [Config Instructions](readme_bestpractices.md#Config-Instructions).

guides/readme_bestpractices.md

@@ -0,0 +1,59 @@
+This file contains suggested best practices for creating a README file for your MagicMirror² module.  
+
+# Installation Instructions
+
+Your README file should have an "Installation" section that includes a code block that can be pasted into a user's terminal to fully install your module. Here is a good example of an install code block:
+
+## Example if your module has no dependencies
+
+````
+```bash
+cd ~/MagicMirror/modules
+git clone https://github.com/MyUsername/MMM-MyModule
+```
+````
+
+## Example if your module has dependencies
+
+````
+```bash
+cd ~/MagicMirror/modules
+git clone https://github.com/MyUsername/MMM-MyModule
+cd MMM-MyModule
+npm ci --omit=dev
+```
+````
+
+## Tips
+
+* The code block should not be broken up into multiple separate blocks for each line of code so that users can copy and paste the entire block into their terminal and execute the install with one click.
+* The opening `` ``` `` of your code block should be followed by "`sh`" or "`bash`" so that the code block is styled as shell script.
+* If your module has required dependencies, `npm ci` is preferable to `npm install` in many circumstances because it will repeatably instruct users' machines not to recreate the `package-lock.json` file.
+* Adding `--omit=dev` to the `npm ci` or `npm install` command will instruct users' machines not to install developer dependencies that are unneeded by most users, which will save on install time and disk space.
+
+# Update Instructions
+
+Your README file should have an "Update" section that includes a code block that can be pasted into a user's terminal to update your module.
+
+# Config Instructions
+
+Your README file should have a "Config" or "Configuration" section that includes an example config block that can be pasted into user's `config.js` files.  Here is a good example of a config code block:
+
+````
+```js
+{
+  module: MMM-MyModule,
+  position: bottom_bar,
+  config: {
+    myCustomVariable: 400,
+    MySecondCustomVariable: false
+  }
+},
+```
+````
+
+## Tips
+
+* The opening `` ``` `` of your code block should be followed by "`js`" or "`javascript`" so that the code block is styled as javasript.
+* The final `}` should be followed by a `,` so that the block can be copied and pasted straight into users' `config.js` files without throwing errors.
+* The example config should provide a minimal demo configuration that will get your module working if pasted directly into a user's `config.js` file.

scripts/check_modules.py

@@ -359,15 +359,15 @@ def check_modules():
                                     file_path, "## Updat")
                                 if not found_update_section:
                                     module["issues"].append(
-                                        "Recommendation: The README seems not to have an update section (like `## Update`). Please add one."
+                                        "Recommendation: The README seems not to have an update section (like `## Update`). Please add one ([basic instructions](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/blob/main/guides/readme_bestpractices.md#Update-Instructions))."
                                     )
 
                                 # Search for an install section in README
                                 found_install_section = search_in_file(
                                     file_path, "## Install")
                                 if not found_install_section:
                                     module["issues"].append(
-                                        "Recommendation: The README seems not to have an install section (like `## Installation`). Please add one."
+                                        "Recommendation: The README seems not to have an install section (like `## Installation`). Please add one ([basic instructions](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/blob/main/guides/readme_bestpractices.md#Installation-Instructions))."
                                     )
 
                                 # Search for "modules: [" in README
@@ -377,7 +377,7 @@ def check_modules():
 
                                 if found_modules_string and module["name"] not in false_positive_modules:
                                     module["issues"].append(
-                                        "Recommendation: The README seems to have a modules array (Found `modules: [`). This is usually not necessary. Please remove it if it is not needed."
+                                        "Recommendation: The README seems to have a modules array (Found `modules: [`). This is usually not necessary. Please remove it if it is not needed ([basic instructions](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/blob/main/guides/readme_bestpractices.md#Config-Instructions))."
                                     )
 
                                 # Search for config example with regex "\{\s*[^}]*?\s*config:\s*\{\s*[^}]*\}(?!\s*,\s*\})\s*\}"
@@ -389,7 +389,7 @@ def check_modules():
                                     false_positive_modules = ["MMM-CalendarExt2"]
                                     if not found_modules_string and module["name"] not in false_positive_modules:
                                         module["issues"].append(
-                                            "Recommendation: The README seems not to have a config example. Please add one."
+                                            "Recommendation: The README seems not to have a config example. Please add one ([basic instructions](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/blob/main/guides/readme_bestpractices.md#Config-Instructions))."
                                         )
                                 else:
                                     # Check if the config example has an trailing comma
@@ -398,7 +398,7 @@ def check_modules():
                                     false_positive_modules = ["MMM-MealieMenu", "MMM-Remote-Control"]
                                     if not found_trailing_comma and module["name"] not in false_positive_modules:
                                         module["issues"].append(
-                                            "Recommendation: The README seems to have a config example without a trailing comma. Please add one."
+                                            "Recommendation: The README seems to have a config example without a trailing comma. Please add one ([basic instructions](https://github.com/MagicMirrorOrg/MagicMirror-3rd-Party-Modules/blob/main/guides/readme_bestpractices.md#Config-Instructions))."
                                         )
 
                             if len(module["issues"]) < 1: