From 3c3ec80525b97e8a24db4c44bbf42a7b4e089056 Mon Sep 17 00:00:00 2001
From: undergroundwires <git@undergroundwires.dev>
Date: Wed, 26 Jan 2022 08:14:25 +0100
Subject: [PATCH] Improve documentation for developing

Move existing documentation to `docs/development.md` to have simpler
`README.md` but more dedicated and extensive documentation for
development.

Improve existing documentation for different commands for the project.

Document VSCode recommendations in `extensions.json` file and add
exception in `.gitignore` to be able to add it to repository.
---
 .gitignore              |  3 ++-
 .vscode/extensions.json | 23 +++++++++++++++++++
 README.md               | 20 ++--------------
 docs/development.md     | 51 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 78 insertions(+), 19 deletions(-)
 create mode 100644 .vscode/extensions.json
 create mode 100644 docs/development.md

diff --git a/.gitignore b/.gitignore
index e8cf0c66..6e46464a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,8 @@
 node_modules
 dist/
 .vs
-.vscode
+.vscode/**/*
+!.vscode/extensions.json
 #Electron-builder output
 /dist_electron
 # Cypress
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 00000000..c8cb1890
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,23 @@
+{
+  "recommendations": [
+    // Common
+    "editorconfig.editorconfig",        // Applies .editorconfig to follow project style.
+    "wengerk.highlight-bad-chars",      // Highlights bad chars.
+    "wayou.vscode-todo-highlight",      // Highlights TODO.
+    "wix.vscode-import-cost",           // Shows in KB how much a require include in code.
+    // Documentation
+    "davidanson.vscode-markdownlint",   // Lints markdown.
+    // TypeScript / JavaScript
+    "dbaeumer.vscode-eslint",           // Lints JavaScript/TypeScript.
+    "pmneo.tsimporter",                 // Provides better auto-complete for TypeScripts imports.
+    // Vue
+    "jcbuisson.vue",                    // Highlights syntax.
+    "octref.vetur",                     // Adds Vetur, Vue tooling support.
+    // Scripting
+    "timonwong.shellcheck",             // Lints bash files.
+    "ms-vscode.powershell",             // Lints PowerShell files.
+    "ms-python.python",                 // Lints Python files.
+    // Distribution
+    "ms-azuretools.vscode-docker"       // Adds Docker support.
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
index ceaf673f..a0fe223e 100644
--- a/README.md
+++ b/README.md
@@ -126,25 +126,9 @@
      - 🙏 For any new script, please add `revertCode` and `docs` values if possible.
   3. Send a pull request 👌
 
-## Commands
+## Development
 
-- Project setup: `npm install`
-- Testing
-  - Run unit tests: `npm run test:unit`
-  - Run integration tests: `npm run test:integration`
-  - Run e2e (end-to-end) tests
-    - Interactive mode with GUI: `npm run test:e2e`
-    - Headless mode without GUI: `npm run test:e2e -- --headless`
-  - Lint: `npm run lint`
-- **Desktop app**
-  - Development: `npm run electron:serve`
-  - Production: `npm run electron:build` to build an executable
-- **Webpage**
-  - Development: `npm run serve` to compile & hot-reload for development.
-  - Production: `npm run build` to prepare files for distribution.
-  - Or run using Docker:
-    1. Build: `docker build -t undergroundwires/privacy.sexy:0.11.3 .`
-    2. Run: `docker run -it -p 8080:80 --rm --name privacy.sexy-0.11.3 undergroundwires/privacy.sexy:0.11.3`
+See [docs/development.md](./docs/development.md) for Docker usage, running/building application, development best-practices along with other information related to development.
 
 ## Architecture overview
 
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 00000000..e1962dd3
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,51 @@
+# Development
+
+Before your commit, a good practice is to:
+
+1. [Run unit tests](#testing)
+2. [Lint your code](#linting)
+
+You could run other types of tests as well, but they may take longer time and overkill for your changes. All tests are executed inside a pull request.
+
+## Commands
+
+### Prerequisites
+
+- Install node >15.x.
+- Install dependencies using `npm install`.
+
+### Testing
+
+- Run unit tests: `npm run test:unit`
+- Run integration tests: `npm run test:integration`
+- Run e2e (end-to-end) tests
+  - Interactive mode with GUI: `npm run test:e2e`
+  - Headless mode without GUI: `npm run test:e2e -- --headless`
+
+### Linting
+
+- Lint all (recommended 💡): `npm run lint`
+- Markdown: `npm run lint:md`
+- Markdown consistency `npm run lint:md:consistency`
+- Markdown relative URLs: `npm run lint:md:relative-urls`
+- JavaScript/TypeScript: `npm run lint:eslint`
+- Yaml: `npm run lint:yaml`
+
+### Running
+
+- Run in local server: `npm run serve`
+  - 💡 Meant for local development with features such as hot-reloading.
+- Run using Docker:
+  1. Build: `docker build -t undergroundwires/privacy.sexy:latest .`
+  2. Run: `docker run -it -p 8080:80 --rm --name privacy.sexy undergroundwires/privacy.sexy:latest`
+
+### Building
+
+- Build web application: `npm run build`
+- Build desktop application: `npm run electron:build`
+
+## Recommended extensions
+
+You should use EditorConfig to follow project style.
+
+For Visual Studio Code, recommended extensions are defined in [`.vscode/extensions.json`](./../.vscode/extensions.json).