chore: add local QA script, docs

Signed-off-by: Kristina Devochko <[email protected]>

link-config.json

@@ -12,12 +12,8 @@
       "replacement": "/website/static/images/"
     },
     {
-      "pattern": "^/landscape/",
-      "replacement": "/website/content/landscape/_index.md"
-    },
-    {
-      "pattern": "^/landscape-ko/",
-      "replacement": "/website/content/landscape/SustainabilityUseCasesAndLandscape2023.ko.md"
+      "pattern": "^/landscape(.+)?/",
+      "replacement": "/website/content/landscape/"
     },
     {
       "pattern": "^/",

package.json

@@ -9,11 +9,12 @@
     "cd:site": "npm run _cd:site -- npm run",
     "check:links:internal": "npm run cd:site check:links:internal",
     "check:links": "npm run cd:site check:links",
-    "check:markdown": "npx markdownlint '*.md' '*/*.md' website/content",
+    "check:markdown": "npx markdownlint-cli2 '*.md' '*/*.md' website/content",
     "fix:markdown": "npm run check:markdown -- --fix",
     "get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}",
-    "precheck:markdown": "npm list markdownlint-cli || npm install markdownlint-cli",
+    "precheck:markdown": "npm list markdownlint-cli2 || npm install markdownlint-cli2",
     "prepare": "npm run site-install",
+    "qa:dev": "./qa-checks-local.sh",
     "serve:dev": "npm run cd:site serve:dev",
     "serve": "npm run cd:site serve",
     "site-install": "npm run _cd:site -- npm install",
@@ -22,7 +23,7 @@
   "devDependencies": {
     "cspell": "^8.0.0",
     "htmltest-bin": "github:chalin/htmltest-bin#semver:0.17.0",
-    "markdownlint-cli": "^0.37.0",
+    "markdownlint-cli2": "^0.10.0",
     "prettier": "^3.0.1"
   },
   "enginesComment": "Ensure that engines.node value stays consistent with the project's .nvmrc",

qa-checks-local.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+echo -e "\033[1;35m Checking presence of QA tools...If not present, a tool will be installed.\033[0m\n"
+
+npm list markdownlint-cli2 || npm install -g markdownlint-cli2
+npm list markdown-link-check || npm install -g markdown-link-check
+npm list cspell || npm install -g cspell
+
+echo -e "\033[1;35m Checking modified files...\033[0m\n"
+files=$(git diff --name-only --diff-filter=AM main $HEAD | grep '\.md$')
+
+echo -e "\033[1;35m ######## LINTING ########\033[0m\n"
+echo -e "\033[1;35m Running Markdown linting on modified files...\033[0m\n"
+for file in $files; do
+    npx markdownlint-cli2 --fix --config ./.markdownlint.json "$file"
+done
+
+echo -e "\n\033[1;35m ######## SPELLING ########\033[0m\n"
+echo -e "\033[1;35m Running spelling validation on modified files...\033[0m\n"
+for file in $files; do
+    npx cspell --config ./cspell.json "$file"
+done
+
+echo -e "\n\033[1;35m ######## LINKS ########\033[0m\n"
+echo -e "\033[1;35m Running Markdown links validation on modified files...\033[0m\n"
+for file in $files; do
+    npx markdown-link-check --config ./link-config.json --progress --verbose "$file"
+done
+
+echo -e "\n\033[1;32m Done!\033[0m"

writing-style.md

@@ -29,6 +29,34 @@ good sources for content guidelines at the bottom of this guide.
 * All other file and directory names should be all lower case with dashes to
   separate words.
 
+## Pull Request Quality Checks
+
+As part of every pull request following quality checks are being executed to ensure that submitted content is compliant with existing best practices for spelling, document formatting and link formats:
+
+* [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) tool is used to verify correct Markdown file formatting;
+* [cSpell](http://cspell.org) is used to verify that content is compliant with established spelling rules;
+* [markdown-link-check](https://github.com/tcort/markdown-link-check) is used to verify that all the links are valid and properly constructed;
+
+In case any of the modified files in the PR violate any of the checks a "Quality Checks" build will fail.
+
+### Running Quality Checks locally
+
+We encourage everyone to execute quality checks locally prior to creating a pull request to ensure that you can fix as many errors as possible before going through a code review process. To run the quality checks locally you can run ```npm run qa:dev``` command from the root of the tag-env-sustainability repository - this command will trigger a [qa-checks-local.sh](./qa-checks-local.sh) script that will perform all the validations mentioned above on the files that you've modified. It will also install the tools mentioned above if those don't exist locally. If any issues will be identified by the script those will be written to the terminal session where the command has been triggered so that you can easily go through and follow up the detected errors accordingly.
+
+> Please note that minimum version ```v18.0.0``` of ```Node.js``` is required for all the tools to run successfully. You can install latest ```Node.js``` version with ```nvm install --lts``` command or you can refer following article for more information [How to update Node.js and NPM to next version?](https://www.geeksforgeeks.org/how-to-update-node-js-and-npm-to-next-version)
+
+### Fixing QA errors
+
+Every tool provides quite descriptive messages regarding the location of the error and how it should be fixed, but below is a quick guide for additional help and reference.
+
+1. **Markdown linting.** ```markdownlint-cli2``` tool is configured to automatically fix those issues that it can fix automatically, but if there are issues that can't be fixed automatically, an error with file and location will be printed out for your reference. For example, ```writing-style.md MD024/no-duplicate-heading/no-duplicate-header: Multiple headings with the same content markdownlint(MD024) [Ln 54, Col 1]``` is an error message that states that it has identified a heading of the same level on **line 54** of **writing-style.md** file, which is where you would need to update it to resolve the issue. More rules with explanations can be found [here](https://github.com/DavidAnson/markdownlint/blob/main/README.md#rules--aliases).
+
+2. **Spelling.** ```cSpell``` tool has a configuration file called [cspell.json](./cspell.json), that is located in the root of the repo, and it defines a set of rules that the tool following during its execution. It checks the words towards a set of default dictionaries, words that we have identified to always be correct and a set of patterns that the tool shall ignore and not scan (like code blocks and Markdown/HTML specific link syntax, etc.). In addition we have created a custom TAG ENV dictionary, [tag-custom-dictionary-cspell.txt](./tag-custom-dictionary-cspell.txt), where we can add words that are correct, but are not present in default dictionaries. In case you get ```Unknown word``` error you will need to verify that the word is correctly spelled and if not, update it accordingly on the line and in the file that the tool is referring to. If the word is correct, you may add it to the TAG ENV custom dictionary mentioned above.
+
+3. **Markdown links.** ```markdown-link-check``` tool has a configuration file called [link-config.json](./link-config.json), that is located in the root of the repo, and it defines a set of rules that the tool following during its execution. It checks for link patterns that it should ignore and the links that should be modified to verify their validity. A good example here is where we place the images - the location for the images is different in the source code and the deployed website, therefore we need to perform validation towards a correct path which may not be the one referenced by the Markdown files in the source code (because those use the reference path that will be valid once the website is built and deployed). If the tool flags a specific link as invalid you need to verify what the error is and modify the link accordingly, on the line and in the file that the tool is referring to. For example, ```FILE: writing-style.md  [✖] https://eco-qube.eu/ → Status: 410``` points to that the respective link in ```writing-style.md``` file is no longer valid and we can confirm it by navigating to the link in the browser. To fix that I would need to update ```https://eco-qube.eu``` with ```https://www.ecoqube.org```, which is its valid alternative.
+
+This guide is not extensive and if you're still experiencing issues that are not covered by this guide, don't hesitate to mention this as part of your pull request, reach out to the TAG ENV community on Slack or raise a GitHub issue and community members will be happy to help you out and progress with your work!😊
+
 ## Sources
 
 <!-- cSpell:ignore Opps --->