From 3b0e52380df61e60979fb53e9991918ee379bc5e Mon Sep 17 00:00:00 2001 From: Alan Rodas Bonjour Date: Fri, 2 Feb 2024 15:41:30 -0300 Subject: [PATCH] docs: added documentation for all sections This is a major change in our guidelines, where now there are multiple sections, that include not only a simple technology list, or project liting, but an extensive guide on the methodology for contribution, the styling we use and more. --- .editorconfig | 11 +- .husky/commit-msg | 16 +- .husky/pre-commit | 52 +++ .husky/pre-push | 32 +- .husky/prepare-commit-msg | 19 +- .npmignore | 25 ++ .npmrc | 3 + .vscode/extensions.json | 7 + .vscode/launch.json | 24 ++ .vscode/settings.json | 18 + CHANGELOG.md | 32 ++ CONTRIBUTING.md | 7 + eleventy.config.js | 18 - markdownlint.config.js | 114 ++++++ package-scripts.js | 78 +++++ package.json | 35 +- src/css/main.scss | 54 ++- src/css/prism-vs.min.css | 134 +++++++- src/css/prism-vsc-dark-plus.min.css | 219 +++++++++++- .../diagram-of-components.svg | 0 src/pages/about-guidelines/index.md | 84 ++--- src/pages/architecture/index.md | 239 ++++++++++--- .../coding-contributor/index.md | 7 - .../coding-standards/coding-team/index.md | 7 - .../coding-standards/documentation/index.md | 7 - src/pages/coding-standards/index.md | 98 ------ .../naming-conventions/index.md | 7 - .../project-organization/index.md | 7 - src/pages/coding/code-styling/index.md | 120 +++++++ .../commit-conventions/index.md | 33 +- src/pages/coding/index.md | 48 +++ .../coding/project-organization/index.md | 165 +++++++++ src/pages/coding/submission-workflow/index.md | 219 ++++++++++++ .../testing/index.md | 38 +- .../coding/writing-documentation/index.md | 54 +++ src/pages/governance/communication/index.md | 36 ++ src/pages/governance/contact/index.md | 16 - src/pages/governance/core-team/index.md | 35 -- src/pages/governance/decision-making/index.md | 90 ++++- src/pages/governance/index.md | 20 +- src/pages/index.md | 16 +- src/pages/introduction/index.md | 26 +- .../technologies/environment-setup/index.md | 259 ++++++++++++++ src/pages/technologies/index.md | 19 +- .../installation-tutorial/index.md | 116 ------- src/pages/technologies/services-list/index.md | 46 ++- .../technologies/technology-list/index.md | 324 ++++++------------ src/templates/includes/footer.html | 8 + test/{verify-links.js => test-runner.js} | 71 ++-- test/verify-links.test.js | 9 + 50 files changed, 2309 insertions(+), 813 deletions(-) mode change 100644 => 100755 .editorconfig create mode 100755 .husky/pre-commit create mode 100644 .npmignore create mode 100644 .npmrc create mode 100755 .vscode/extensions.json create mode 100755 .vscode/launch.json create mode 100755 .vscode/settings.json create mode 100755 CHANGELOG.md create mode 100755 CONTRIBUTING.md create mode 100644 markdownlint.config.js create mode 100755 package-scripts.js rename src/img/{ => architecture}/diagram-of-components.svg (100%) delete mode 100644 src/pages/coding-standards/coding-contributor/index.md delete mode 100644 src/pages/coding-standards/coding-team/index.md delete mode 100644 src/pages/coding-standards/documentation/index.md delete mode 100644 src/pages/coding-standards/index.md delete mode 100644 src/pages/coding-standards/naming-conventions/index.md delete mode 100644 src/pages/coding-standards/project-organization/index.md create mode 100644 src/pages/coding/code-styling/index.md rename src/pages/{coding-standards => coding}/commit-conventions/index.md (80%) create mode 100644 src/pages/coding/index.md create mode 100644 src/pages/coding/project-organization/index.md create mode 100644 src/pages/coding/submission-workflow/index.md rename src/pages/{coding-standards => coding}/testing/index.md (96%) create mode 100644 src/pages/coding/writing-documentation/index.md create mode 100644 src/pages/governance/communication/index.md delete mode 100644 src/pages/governance/contact/index.md delete mode 100644 src/pages/governance/core-team/index.md create mode 100644 src/pages/technologies/environment-setup/index.md delete mode 100644 src/pages/technologies/installation-tutorial/index.md rename test/{verify-links.js => test-runner.js} (68%) create mode 100644 test/verify-links.test.js diff --git a/.editorconfig b/.editorconfig old mode 100644 new mode 100755 index 1a17268..9966bd6 --- a/.editorconfig +++ b/.editorconfig @@ -1,12 +1,19 @@ +# http://editorconfig.org + root = true [*] charset = utf-8 +end_of_line = lf indent_style = space indent_size = 4 -end_of_line = lf -insert_final_newline = true trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +trim_trailing_whitespace = false +# Use 2 spaces since npm does not respect custom indentation settings [package.json] +indent_style = space indent_size = 2 diff --git a/.husky/commit-msg b/.husky/commit-msg index f7c86d6..0789a28 100755 --- a/.husky/commit-msg +++ b/.husky/commit-msg @@ -1,5 +1,14 @@ #!/usr/bin/env sh +# Load husky +. "$(dirname -- "$0")/_/husky.sh"; + +# Read parameters +COMMIT_MSG_FILE=$1; + +# Set failing on command fail, pipe fail, and undefined variable use +set -euo pipefail + # This hook is invoked by git-commit and git-merge, and can be # bypassed with the --no-verify option. It takes a single # parameter, the name of the file that holds the proposed commit @@ -15,13 +24,6 @@ # The default commit-msg hook, when enabled, detects duplicate # Signed-off-by trailers, and aborts the commit if one is found. -# Load husky -. "$(dirname -- "$0")/_/husky.sh"; -npx --no -- commitlint --edit ${1}; - -# Read parameters -COMMIT_MSG_FILE=$1; - # We use this hook to run "commitlint", that verifies that the # message sent has the correct format for the project, aborting otherwise. diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 0000000..51fb707 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,52 @@ +#!/usr/bin/env sh + +# Load husky +. "$(dirname -- "$0")/_/husky.sh"; + +# Read parameters +# NOTHING TO READ HERE + +# Set failing on command fail, pipe fail, and undefined variable use +set -euo pipefail + +# This hook is invoked by git-commit, and can be bypassed with the +# --no-verify option. It takes no parameters, and is invoked before +# obtaining the proposed commit log message and making a commit. +# Exiting with a non-zero status from this script causes the git +# commit command to abort before creating a commit. + +# The default pre-commit hook, when enabled, catches introduction of +# lines with trailing whitespaces and aborts the commit when such a +# line is found. + +# All the git commit hooks are invoked with the environment variable +# GIT_EDITOR=: if the command will not bring up an editor to modify +# the commit message. + +# The default pre-commit hook, when enabled and with the hooks.allownonascii +# config option unset or set to false prevents the use of non-ASCII filenames. + +# We currently use this hook to update the changelog of the project +# and make sure all files are prettified before sending them to the commit. +# Generated files are added to the commit. + +# Show welcome message +echo "**************************"; +echo "Running pre commit hooks"; +echo "**************************"; +echo ""; + +# Run prettify +echo "Run prettify\n"; +npx --no -- gobstones-scripts run prettify --silent ; + +# Run changelog +echo "\nRun changelog\n"; +npx --no gobstones-scripts run changelog --silent ; + +# Add all generated files +echo "\nAdd generated files to commit\n"; +git add --all; + +# Exit +exit 0; diff --git a/.husky/pre-push b/.husky/pre-push index 08ce28f..8f822b7 100755 --- a/.husky/pre-push +++ b/.husky/pre-push @@ -8,11 +8,7 @@ REMOTE_NAME=$1; REMOTE_URL=$2; # Read the input and split it approprietly INPUT=$(cat); -INPUT_ARR[0]=''; -INPUT_ARR[1]=''; -INPUT_ARR[2]=''; -INPUT_ARR[3]=''; -read -a INPUT_ARR <<< "$INPUT"; +INPUT_ARR=($INPUT); LOCAL_REF=${INPUT_ARR[0]} LOCAL_OBJ_NAME=${INPUT_ARR[1]} @@ -27,7 +23,7 @@ set -euo pipefail # which provide the name and location of the destination remote, # if a named remote is not being used both values will be the same. -# Information about what is to be pushed is provided on the hook`s +# Information about what is to be pushed is provided on the hook’s # standard input with lines of the form: # SP SP SP LF @@ -48,17 +44,6 @@ set -euo pipefail # pushing anything. Information about why the push is rejected may be # sent to the user by writing to standard error. -# If pushing a tag, generate doc and push them as -# a "docs" branch in the remote. -case "$LOCAL_REF" in - refs\/tags*) - # Apply specific code when publishing tags - IS_TAG=1;; - *) - # Apply specific code when publishing any branch - IS_TAG=0;; -esac - # We currently use this hook to verify that any commit (to any branch) # passes the tests configured. # If a tag is being pushed, then, we generate the documentation @@ -75,6 +60,17 @@ echo ""; # Run all the tests echo "Running tests"; -npm run test; +npx --no -- gobstones-scripts run test --silent; + +# If pushing a tag, generate doc and push them as +# a "docs" branch in the remote. +case "$LOCAL_REF" in + refs\/tags*) + # Apply specific code when publishing tags + echo "\nYour tag is being pushed...\n";; + *) + # Apply specific code when publishing any branch + echo "\nYour branch is being pushed...\n";; +esac exit 0; diff --git a/.husky/prepare-commit-msg b/.husky/prepare-commit-msg index de3f65c..49d01ff 100755 --- a/.husky/prepare-commit-msg +++ b/.husky/prepare-commit-msg @@ -1,5 +1,16 @@ #!/usr/bin/env sh +# Load husky +. "$(dirname -- "$0")/_/husky.sh"; + +# Read parameters +COMMIT_MSG_FILE=$1; +COMMIT_SOURCE=$2; +SHA1=$3; + +# Set failing on command fail, pipe fail, and undefined variable use +set -euo pipefail + # This hook is invoked by git-commit right after preparing # the default log message, and before the editor is started. @@ -24,14 +35,6 @@ # The sample prepare-commit-msg hook that comes with Git removes # the help message found in the commented portion of the commit template. -# Load husky -. "$(dirname -- "$0")/_/husky.sh"; - -# Read parameters -COMMIT_MSG_FILE=$1; -COMMIT_SOURCE=$2; -SHA1=$3; - # We use this hook to run "cz", that forces the build of a # semantic commit message through a prompt. diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..5ef1a1c --- /dev/null +++ b/.npmignore @@ -0,0 +1,25 @@ +# Editor and style files +.editorconfig +.prettierignore +.prettierrc +.eslintrc.js +.vscode/* +.github/* +.husky/* + +# tests +test/* +jest.config.js +coverage + +# docs +docs + +# Building Configuration Files +webpack.config.js +rollup.config.js +tsconfig.json +package-scripts.js + +# Additional documentation +TODO.md diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..2a34138 --- /dev/null +++ b/.npmrc @@ -0,0 +1,3 @@ +strict-peer-dependencies=false +auto-install-peers=false +legacy-peer-deps=true diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100755 index 0000000..972a692 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,7 @@ +{ + "recommendations": [ + "streetsidesoftware.code-spell-checker", + "editorconfig.editorconfig", + "esbenp.prettier-vscode" + ] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100755 index 0000000..95a5e1a --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,24 @@ +{ + // Use IntelliSense to learn about possible Node.js debug attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "Run Dev (npm run dev)", + "request": "launch", + "runtimeArgs": ["run-script", "dev"], + "runtimeExecutable": "npm", + "skipFiles": ["/**"], + "type": "node" + }, + { + "name": "Test (npm run test)", + "request": "launch", + "runtimeArgs": ["run-script", "test"], + "runtimeExecutable": "npm", + "skipFiles": ["/**"], + "type": "node" + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100755 index 0000000..81d3a00 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,18 @@ +{ + // Node and npm configuration + "npm.autoDetect": "on", + "debug.node.autoAttach": "smart", + "files.exclude": { + "tsconfig.build.json": true + }, + // Code style, regular and ESLint related + "files.trimTrailingWhitespace": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "eslint.validate": ["typescript"], + "editor.codeActionsOnSave": { + "source.fixAll": "explicit" + }, + "editor.formatOnSave": false, + // CSpell + "cSpell.words": [] +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100755 index 0000000..b1208ac --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,32 @@ +# [0.1.0](https://github.com/gobstones/gobstones-guidelines/compare/v0.0.1...v0.1.0) (2024-02-02) + + +### Build System + +* transform the guideline into a webpage ([83653ff](https://github.com/gobstones/gobstones-guidelines/commit/83653ffad470464d161885dfdd2d80427544b0ea)) + + +### BREAKING CHANGES + +* The whole project structure has changed. + + + +# [0.1.0](https://github.com/gobstones/gobstones-guidelines/compare/v0.0.1...v0.1.0) (2024-02-02) + + +### Build System + +* transform the guideline into a webpage ([83653ff](https://github.com/gobstones/gobstones-guidelines/commit/83653ffad470464d161885dfdd2d80427544b0ea)) + + +### BREAKING CHANGES + +* The whole project structure has changed. + + + +## 0.0.1 (2022-10-26) + + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100755 index 0000000..6e5f284 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,7 @@ +# Contibution Guidelines + +Please, before contributing to this project, take a moment to read our [Contributions Guidelines](https://github.com/gobstones/gobstones-guidelines). + +Also, be sure to understand that by contributing you agree to allow +the project owners to license your work under the terms of our +[License](https://github.com/gobstones/gobstones-guidelines/blob/main/LICENSE). diff --git a/eleventy.config.js b/eleventy.config.js index 85e9c97..ecb81a3 100644 --- a/eleventy.config.js +++ b/eleventy.config.js @@ -2,7 +2,6 @@ const isCi = require('is-ci'); const markdownIt = require('markdown-it'); const markdownItAnchor = require('markdown-it-anchor'); -const markdownItReplaceLink = require('markdown-it-replace-link'); const EleventySassPlugin = require('eleventy-sass'); const { EleventyHtmlBasePlugin } = require("@11ty/eleventy"); @@ -43,23 +42,6 @@ module.exports = function (el) { visuallyHiddenClass: 'hidden' }) }) - .use(markdownItReplaceLink, { - /* - replaceLink: function (link, env, token, htmlToken) { - if (link.match(/^(?!www\.|(?:http|ftp|mailto)s?:\/\/|[A-Za-z]:\\|\/\/).* /)) { - if (env.permalink.startsWith('/governance')) { - console.log(env); - console.log(token); - console.log(htmlToken); - } - const updated = `${pathPrefix}${link.startsWith('/') ? '' : '/'}${link}`; - // console.log(`Updating link: ${link} -> ${updated}`); - return link; - } - return link; - } - */ - }) ); /* diff --git a/markdownlint.config.js b/markdownlint.config.js new file mode 100644 index 0000000..e9d80f0 --- /dev/null +++ b/markdownlint.config.js @@ -0,0 +1,114 @@ +// You can see the list of rules at: https://github.com/DavidAnson/markdownlint + +module.exports = { + default: true, + 'heading-increment': true, + 'heading-style': { style: 'atx' }, + 'ul-style': { style: 'asterisk' }, + 'list-indent': true, + 'ul-indent': { indent: 4, start_indented: false }, + 'no-trailing-spaces': { + br_spaces: 2, + list_item_empty_lines: false, + strict: false + }, + 'no-hard-tabs': { + code_blocks: true, + ignore_code_languages: [], + spaces_per_tab: 4 + }, + 'no-reversed-links': true, + 'no-multiple-blanks': { + maximum: 1 + }, + 'line-length': false, + 'commands-show-output': true, + 'no-missing-space-atx': true, + 'no-multiple-space-atx': true, + 'no-missing-space-closed-atx': true, + 'no-multiple-space-closed-atx': true, + 'blanks-around-headings': { + lines_above: 1, + lines_below: 1 + }, + 'heading-start-left': true, + 'no-duplicate-heading': { siblings_only: true }, + 'single-title': { + level: 1, + front_matter_title: '' + }, + 'no-trailing-punctuation': { + punctuation: '.,;:!。，；：！' + }, + 'no-multiple-space-blockquote': true, + 'no-blanks-blockquote': true, + 'ol-prefix': { style: 'ordered' }, + 'list-marker-space': { + // Spaces for single-line unordered list items + ul_single: 1, + // Spaces for single-line ordered list items + ol_single: 1, + // Spaces for multi-line unordered list items + ul_multi: 1, + // Spaces for multi-line ordered list items + ol_multi: 1 + }, + 'blanks-around-fences': { + // Include list items + list_items: true + }, + 'blanks-around-lists': true, + 'no-inline-html': { allowed_elements: [] }, + 'no-bare-urls': true, + 'hr-style': { style: '---------------------------------------------------------------------' }, + 'no-emphasis-as-heading': { punctuation: '.,;:!?。，；：！' }, + 'no-space-in-emphasis': true, + 'no-space-in-code': true, + 'no-space-in-links': true, + 'fenced-code-language': { + allowed_languages: ['sh', 'ts', 'yaml', 'json'], + language_only: true + }, + 'first-line-heading': { + level: 1, + front_matter_title: '' + }, + 'no-empty-links': true, + 'required-headings': false, + 'proper-names': { + code_blocks: false, + html_elements: true, + names: [ + 'TypeScript', + 'JavaScript', + 'Gobstones', + 'GobstonesWeb', + 'React', + 'StoryBook', + 'Git' + ] + }, + 'no-alt-text': true, + 'code-block-style': { style: 'fenced' }, + 'single-trailing-newline': true, + 'code-fence-style': { style: 'backtick' }, + 'emphasis-style': { style: 'underscore' }, + 'strong-style': { style: 'asterisk' }, + 'link-fragments': true, + 'reference-links-images': { shortcut_syntax: false }, + 'link-image-reference-definitions': { + ignored_definitions: [] + }, + 'link-image-style': { + autolink: false, + inline: true, + full: false, + collapsed: false, + shortcut: false, + url_inline: true + }, + 'table-pipe-style': { + style: 'leading_and_trailing' + }, + 'table-column-count': true +}; diff --git a/package-scripts.js b/package-scripts.js new file mode 100755 index 0000000..3097659 --- /dev/null +++ b/package-scripts.js @@ -0,0 +1,78 @@ +/* eslint-disable @typescript-eslint/no-var-requires */ +const { tasks } = require('@gobstones/gobstones-scripts'); + +const defaultConfiguration = { + options: { + scripts: false, + logLevel: 'warn', + 'help-style': 'basic' + }, + scripts: { + default: { + script: tasks.nps('help'), + hiddenFromHelp: true + }, + + dev: { + script: tasks.serially( + tasks.nps('clean.dist'), + tasks.npx('@11ty/eleventy --serve') + ), + description: 'Run the eleventy server in development mode' + }, + + test: { + script: tasks.serially( + tasks.nps('lint'), + tasks.node('./test/test-runner.js') + ), + description: 'Run the linter and verify all links' + }, + + build: { + script: tasks.serially( + tasks.nps('clean.dist'), + tasks.npx('@11ty/eleventy') + ), + description: 'Build the application into "dist" folder' + }, + + clean: { + script: tasks.nps('clean.dist'), + description: 'Remove all automatically generated files and folders', + hiddenFromHelp: true, + dist: { + script: tasks.remove({ files: './dist' }), + description: 'Delete the dist folder', + hiddenFromHelp: true + } + }, + + lint: { + script: tasks.npx('markdownlint-cli --config markdownlint.config.js "./src/pages/**/*.md"'), + description: 'Run the linter on all the pages (src/pages)', + fix: { + script: tasks.npx('markdownlint-cli --config markdownlint.config.js --fix "./src/pages/**/*.md"'), + description: 'Run the linter on all the pages (src/pages) fixing all auto-fixable errors' + } + }, + + prettify: { + script: tasks.nps('lint'), + description: 'Run the linter attempting to fix all errors' + }, + + changelog: { + script: tasks.npx('conventional-changelog -p angular -i CHANGELOG.md -s'), + description: 'Generate changelog based on tags', + hiddenFromHelp: true, + scratch: { + script: tasks.npx('conventional-changelog -p angular -i CHANGELOG.md -s -r 0'), + description: 'Generate changelog based on tags, starting from scratch', + hiddenFromHelp: true + }, + } + } +}; + +module.exports = defaultConfiguration; diff --git a/package.json b/package.json index 69e9e61..b807b26 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@gobstones/gobstones-guidelines", - "version": "0.0.1", + "version": "0.1.0", "description": "A simple documentation site for Gobstones project coding standards and guidelines.", "repository": { "type": "git", @@ -19,37 +19,30 @@ ], "scripts": { "prepare": "is-ci || husky install", - "start": "npm run dev", - "dev": "rimraf ./dist && npx @11ty/eleventy --serve", - "build": "rimraf ./dist && npx @11ty/eleventy", - "test": "node ./test/verify-links.js", - "doc": "echo \"The project itself is documentation only.\"", - "lint": "echo \"No code to lint. Only documentation here.\"", - "prettify": "echo \"No code to prettify. Only documentation here.\"" + "start": "gobstones-scripts run", + "gbs": "gobstones-scripts" + }, + "config": { + "gobstones-scripts": { + "type": "noCode", + "manager": "npm" + } + }, + "dependencies": { }, "devDependencies": { "@11ty/eleventy": "^2.0.1", "@11ty/eleventy-navigation": "^0.3.5", "@11ty/eleventy-plugin-syntaxhighlight": "^4.2.0", "@11ty/eleventy-server-browsersync": "^1.0.2", - "@commitlint/config-conventional": "^18.4.4", - "@jest/globals": "^29.7.0", - "ansi-colors": "^4.1.3", - "commitizen": "^4.3.0", - "commitlint": "^18.4.4", + "@gobstones/gobstones-scripts": "^0.7.2", "eleventy-sass": "^2.2.1", "husky": "^8.0.3", - "is-ci": "^3.0.1", - "jest": "^29.7.0", "linkinator": "^6.0.4", "markdown-it": "^13.0.1", "markdown-it-anchor": "^8.6.7", "markdown-it-replace-link": "^1.2.1", - "rimraf": "^5.0.5" - }, - "dependencies": { - "@babel/core": "^7.23.7", - "@babel/preset-env": "^7.23.8", - "babel-jest": "^29.7.0" + "markdownlint": "^0.33.0", + "markdownlint-cli": "^0.38.0" } } diff --git a/src/css/main.scss b/src/css/main.scss index 1cd1f33..ff2f31f 100644 --- a/src/css/main.scss +++ b/src/css/main.scss @@ -148,7 +148,11 @@ dl, menu, ol, ul { - margin: 1em 0; + margin: 0; +} + +li { + margin: 0.4em 0; } dd { @@ -158,10 +162,10 @@ dd { code, pre { font-family: Menlo, Monaco, Consolas, "Courier New", monospace; - padding: 0.2em; + padding: 0.15em 0.5em; margin: 0; font-size: 0.875rem; - border-radius: 0.8em; + border-radius: 0.6em; position: relative; background-color: var(--color-inline-code); } @@ -173,11 +177,13 @@ pre { padding: 10px; border: 1px solid var(--color-accent); } + pre code { padding: 0; font-size: 100%; } + blockquote { margin: 1em 0; padding: 0.1em 0.5em 0.1em 1em; @@ -397,6 +403,7 @@ nav.navigation, li { padding: 0; max-width: 100%; + margin: 0; } a { @@ -474,3 +481,44 @@ nav.navigation { } } } + +/** ============== Contact Cards ============== **/ + +.contact-card { + display: flex; + flex-flow: row; + border: 1px solid var(--color-accent); + border-radius: 1em; + padding: 10px 30px; + margin: 10px; + + img { + max-width: 100px; + max-height: 100px; + border: 1px solid var(--color-accent); + border-radius: 100%; + flex: 1; + } + div { + margin-left: 1em; + } + h3 { + font-size: 1.2rem; + margin: 0.2em 0; + } + h4 { + font-size: 1rem; + margin: 0; + color: var(--color-accent); + } + p { + font-size: 0.9rem; + } + a { + color: var(--color-link); + } + a:hover { + text-decoration: underline; + cursor: pointer; + } +} diff --git a/src/css/prism-vs.min.css b/src/css/prism-vs.min.css index cdd6d54..012b61c 100644 --- a/src/css/prism-vs.min.css +++ b/src/css/prism-vs.min.css @@ -1 +1,133 @@ -code[class*=language-],pre[class*=language-]{color:#393a34;font-family:Consolas,"Bitstream Vera Sans Mono","Courier New",Courier,monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;font-size:.9em;line-height:1.2em;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none}pre>code[class*=language-]{font-size:1em}code[class*=language-] ::-moz-selection,code[class*=language-]::-moz-selection,pre[class*=language-] ::-moz-selection,pre[class*=language-]::-moz-selection{background:#c1def1}code[class*=language-] ::selection,code[class*=language-]::selection,pre[class*=language-] ::selection,pre[class*=language-]::selection{background:#c1def1}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto;border:1px solid #ddd;background-color:#fff}:not(pre)>code[class*=language-]{padding:.2em;padding-top:1px;padding-bottom:1px;background:#f8f8f8;border:1px solid #ddd}.token.cdata,.token.comment,.token.doctype,.token.prolog{color:green;font-style:italic}.token.namespace{opacity:.7}.token.string{color:#a31515}.token.operator,.token.punctuation{color:#393a34}.token.boolean,.token.constant,.token.inserted,.token.number,.token.symbol,.token.url,.token.variable{color:#36acaa}.language-autohotkey .token.selector,.language-json .token.boolean,.language-json .token.number,.token.atrule,.token.attr-value,.token.keyword,code[class*=language-css]{color:#00f}.token.function{color:#393a34}.language-autohotkey .token.tag,.token.deleted{color:#9a050f}.language-autohotkey .token.keyword,.token.selector{color:#00009f}.token.important{color:#e90}.token.bold,.token.important{font-weight:700}.token.italic{font-style:italic}.language-json .token.property,.token.class-name{color:#2b91af}.token.selector,.token.tag{color:maroon}.token.attr-name,.token.entity,.token.property,.token.regex{color:red}.token.directive.tag .tag{background:#ff0;color:#393a34}.line-numbers.line-numbers .line-numbers-rows{border-right-color:#a5a5a5}.line-numbers .line-numbers-rows>span:before{color:#2b91af}.line-highlight.line-highlight{background:rgba(193,222,241,.2);background:-webkit-linear-gradient(left,rgba(193,222,241,.2) 70%,rgba(221,222,241,0));background:linear-gradient(to right,rgba(193,222,241,.2) 70%,rgba(221,222,241,0))} \ No newline at end of file +code[class*='language-'], +pre[class*='language-'] { + color: #393a34; + font-family: Consolas, 'Bitstream Vera Sans Mono', 'Courier New', Courier, monospace; + direction: ltr; + text-align: left; + white-space: pre; + word-spacing: normal; + word-break: normal; + font-size: 0.9em; + line-height: 1.2em; + -moz-tab-size: 4; + -o-tab-size: 4; + tab-size: 4; + -webkit-hyphens: none; + -moz-hyphens: none; + -ms-hyphens: none; + hyphens: none; +} +pre > code[class*='language-'] { + font-size: 1em; +} +code[class*='language-'] ::-moz-selection, +code[class*='language-']::-moz-selection, +pre[class*='language-'] ::-moz-selection, +pre[class*='language-']::-moz-selection { + background: #c1def1; +} +code[class*='language-'] ::selection, +code[class*='language-']::selection, +pre[class*='language-'] ::selection, +pre[class*='language-']::selection { + background: #c1def1; +} +pre[class*='language-'] { + padding: 1em; + margin: 0.5em 0; + overflow: auto; + border: 1px solid #6e6e6e; + background-color: #b1b1b1; +} +:not(pre) > code[class*='language-'] { + padding: 0.2em; + padding-top: 1px; + padding-bottom: 1px; + background: #f8f8f8; + border: 1px solid #ddd; +} +.token.cdata, +.token.comment, +.token.doctype, +.token.prolog { + color: green; + font-style: italic; +} +.token.namespace { + opacity: 0.7; +} +.token.string { + color: #a31515; +} +.token.operator, +.token.punctuation { + color: #393a34; +} +.token.boolean, +.token.constant, +.token.inserted, +.token.number, +.token.symbol, +.token.url, +.token.variable { + color: #36acaa; +} +.language-autohotkey .token.selector, +.language-json .token.boolean, +.language-json .token.number, +.token.atrule, +.token.attr-value, +.token.keyword, +code[class*='language-css'] { + color: #00f; +} +.token.function { + color: #53554b; +} +.language-autohotkey .token.tag, +.token.deleted { + color: #9a050f; +} +.language-autohotkey .token.keyword, +.token.selector { + color: #00009f; +} +.token.important { + color: #e90; +} +.token.bold, +.token.important { + font-weight: 700; +} +.token.italic { + font-style: italic; +} +.language-json .token.property, +.token.class-name { + color: #2b91af; +} +.token.selector, +.token.tag { + color: maroon; +} +.token.attr-name, +.token.entity, +.token.property, +.token.regex { + color: red; +} +.token.directive.tag .tag { + background: #ff0; + color: #393a34; +} +.line-numbers.line-numbers .line-numbers-rows { + border-right-color: #a5a5a5; +} +.line-numbers .line-numbers-rows > span:before { + color: #2b91af; +} +.line-highlight.line-highlight { + background: rgba(193, 222, 241, 0.2); + background: -webkit-linear-gradient(left, rgba(193, 222, 241, 0.2) 70%, rgba(221, 222, 241, 0)); + background: linear-gradient(to right, rgba(193, 222, 241, 0.2) 70%, rgba(221, 222, 241, 0)); +} diff --git a/src/css/prism-vsc-dark-plus.min.css b/src/css/prism-vsc-dark-plus.min.css index 19d722f..8d4febe 100644 --- a/src/css/prism-vsc-dark-plus.min.css +++ b/src/css/prism-vsc-dark-plus.min.css @@ -1 +1,218 @@ -code[class*=language-],pre[class*=language-]{color:#d4d4d4;font-size:13px;text-shadow:none;font-family:Menlo,Monaco,Consolas,"Andale Mono","Ubuntu Mono","Courier New",monospace;direction:ltr;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none}code[class*=language-] ::selection,code[class*=language-]::selection,pre[class*=language-] ::selection,pre[class*=language-]::selection{text-shadow:none;background:#264f78}@media print{code[class*=language-],pre[class*=language-]{text-shadow:none}}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto;background:#1e1e1e}:not(pre)>code[class*=language-]{padding:.1em .3em;border-radius:.3em;color:#db4c69;background:#1e1e1e}.namespace{opacity:.7}.token.doctype .token.doctype-tag{color:#569cd6}.token.doctype .token.name{color:#9cdcfe}.token.comment,.token.prolog{color:#6a9955}.language-html .language-css .token.punctuation,.language-html .language-javascript .token.punctuation,.token.punctuation{color:#d4d4d4}.token.boolean,.token.constant,.token.inserted,.token.number,.token.property,.token.symbol,.token.tag,.token.unit{color:#b5cea8}.token.attr-name,.token.builtin,.token.char,.token.deleted,.token.selector,.token.string{color:#ce9178}.language-css .token.string.url{text-decoration:underline}.token.entity,.token.operator{color:#d4d4d4}.token.operator.arrow{color:#569cd6}.token.atrule{color:#ce9178}.token.atrule .token.rule{color:#c586c0}.token.atrule .token.url{color:#9cdcfe}.token.atrule .token.url .token.function{color:#dcdcaa}.token.atrule .token.url .token.punctuation{color:#d4d4d4}.token.keyword{color:#569cd6}.token.keyword.control-flow,.token.keyword.module{color:#c586c0}.token.function,.token.function .token.maybe-class-name{color:#dcdcaa}.token.regex{color:#d16969}.token.important{color:#569cd6}.token.italic{font-style:italic}.token.constant{color:#9cdcfe}.token.class-name,.token.maybe-class-name{color:#4ec9b0}.token.console{color:#9cdcfe}.token.parameter{color:#9cdcfe}.token.interpolation{color:#9cdcfe}.token.punctuation.interpolation-punctuation{color:#569cd6}.token.boolean{color:#569cd6}.token.exports .token.maybe-class-name,.token.imports .token.maybe-class-name,.token.property,.token.variable{color:#9cdcfe}.token.selector{color:#d7ba7d}.token.escape{color:#d7ba7d}.token.tag{color:#569cd6}.token.tag .token.punctuation{color:grey}.token.cdata{color:grey}.token.attr-name{color:#9cdcfe}.token.attr-value,.token.attr-value .token.punctuation{color:#ce9178}.token.attr-value .token.punctuation.attr-equals{color:#d4d4d4}.token.entity{color:#569cd6}.token.namespace{color:#4ec9b0}code[class*=language-javascript],code[class*=language-jsx],code[class*=language-tsx],code[class*=language-typescript],pre[class*=language-javascript],pre[class*=language-jsx],pre[class*=language-tsx],pre[class*=language-typescript]{color:#9cdcfe}code[class*=language-css],pre[class*=language-css]{color:#ce9178}code[class*=language-html],pre[class*=language-html]{color:#d4d4d4}.language-regex .token.anchor{color:#dcdcaa}.language-html .token.punctuation{color:grey}pre[class*=language-]>code[class*=language-]{position:relative;z-index:1}.line-highlight.line-highlight{background:#f7ebc6;box-shadow:inset 5px 0 0 #f7d87c;z-index:0} \ No newline at end of file +code[class*='language-'], +pre[class*='language-'] { + color: #d4d4d4; + font-size: 13px; + text-shadow: none; + font-family: Menlo, Monaco, Consolas, 'Andale Mono', 'Ubuntu Mono', 'Courier New', monospace; + direction: ltr; + text-align: left; + white-space: pre; + word-spacing: normal; + word-break: normal; + line-height: 1.5; + -moz-tab-size: 4; + -o-tab-size: 4; + tab-size: 4; + -webkit-hyphens: none; + -moz-hyphens: none; + -ms-hyphens: none; + hyphens: none; +} +code[class*='language-'] ::selection, +code[class*='language-']::selection, +pre[class*='language-'] ::selection, +pre[class*='language-']::selection { + text-shadow: none; + background: #264f78; +} +@media print { + code[class*='language-'], + pre[class*='language-'] { + text-shadow: none; + } +} +pre[class*='language-'] { + padding: 1em; + margin: 0.5em 0; + overflow: auto; + background: #1e1e1e; +} +:not(pre) > code[class*='language-'] { + padding: 0.1em 0.3em; + border-radius: 0.3em; + color: #db4c69; + background: #1e1e1e; +} +.namespace { + opacity: 0.7; +} +.token.doctype .token.doctype-tag { + color: #569cd6; +} +.token.doctype .token.name { + color: #9cdcfe; +} +.token.comment, +.token.prolog { + color: #6a9955; +} +.language-html .language-css .token.punctuation, +.language-html .language-javascript .token.punctuation, +.token.punctuation { + color: #d4d4d4; +} +.token.boolean, +.token.constant, +.token.inserted, +.token.number, +.token.property, +.token.symbol, +.token.tag, +.token.unit { + color: #b5cea8; +} +.token.attr-name, +.token.builtin, +.token.char, +.token.deleted, +.token.selector, +.token.string { + color: #ce9178; +} +.language-css .token.string.url { + text-decoration: underline; +} +.token.entity, +.token.operator { + color: #d4d4d4; +} +.token.operator.arrow { + color: #569cd6; +} +.token.atrule { + color: #ce9178; +} +.token.atrule .token.rule { + color: #c586c0; +} +.token.atrule .token.url { + color: #9cdcfe; +} +.token.atrule .token.url .token.function { + color: #dcdcaa; +} +.token.atrule .token.url .token.punctuation { + color: #d4d4d4; +} +.token.keyword { + color: #569cd6; +} +.token.keyword.control-flow, +.token.keyword.module { + color: #c586c0; +} +.token.function, +.token.function .token.maybe-class-name { + color: #dcdcaa; +} +.token.regex { + color: #d16969; +} +.token.important { + color: #569cd6; +} +.token.italic { + font-style: italic; +} +.token.constant { + color: #9cdcfe; +} +.token.class-name, +.token.maybe-class-name { + color: #4ec9b0; +} +.token.console { + color: #9cdcfe; +} +.token.parameter { + color: #9cdcfe; +} +.token.interpolation { + color: #9cdcfe; +} +.token.punctuation.interpolation-punctuation { + color: #569cd6; +} +.token.boolean { + color: #569cd6; +} +.token.exports .token.maybe-class-name, +.token.imports .token.maybe-class-name, +.token.property, +.token.variable { + color: #9cdcfe; +} +.token.selector { + color: #d7ba7d; +} +.token.escape { + color: #d7ba7d; +} +.token.tag { + color: #569cd6; +} +.token.tag .token.punctuation { + color: grey; +} +.token.cdata { + color: grey; +} +.token.attr-name { + color: #9cdcfe; +} +.token.attr-value, +.token.attr-value .token.punctuation { + color: #ce9178; +} +.token.attr-value .token.punctuation.attr-equals { + color: #d4d4d4; +} +.token.entity { + color: #569cd6; +} +.token.namespace { + color: #4ec9b0; +} +code[class*='language-javascript'], +code[class*='language-jsx'], +code[class*='language-tsx'], +code[class*='language-typescript'], +pre[class*='language-javascript'], +pre[class*='language-jsx'], +pre[class*='language-tsx'], +pre[class*='language-typescript'] { + color: #9cdcfe; +} +code[class*='language-css'], +pre[class*='language-css'] { + color: #ce9178; +} +code[class*='language-html'], +pre[class*='language-html'] { + color: #d4d4d4; +} +.language-regex .token.anchor { + color: #dcdcaa; +} +.language-html .token.punctuation { + color: grey; +} +pre[class*='language-'] > code[class*='language-'] { + position: relative; + z-index: 1; +} +.line-highlight.line-highlight { + background: #f7ebc6; + box-shadow: inset 5px 0 0 #f7d87c; + z-index: 0; +} diff --git a/src/img/diagram-of-components.svg b/src/img/architecture/diagram-of-components.svg similarity index 100% rename from src/img/diagram-of-components.svg rename to src/img/architecture/diagram-of-components.svg diff --git a/src/pages/about-guidelines/index.md b/src/pages/about-guidelines/index.md index 1ad3548..9d6908d 100644 --- a/src/pages/about-guidelines/index.md +++ b/src/pages/about-guidelines/index.md @@ -1,56 +1,56 @@ --- -title: About the guidelines +title: About guidelines eleventyNavigation: - key: About the guidelines + key: About guidelines order: 2 --- -# About the gobstones-guidelines project +# About guidelines -The gobstones-guidelines repository contains documentation on the platform architecture, design guidelines, ways to contribute, and standards used, related to the development of **GobstonesWeb2**. +The `gobstones-guidelines` repository contains documentation on the platform architecture, design guidelines, ways to contribute, and standards used, related to the development of **GobstonesWeb2**. [![License](https://img.shields.io/github/license/gobstones/gobstones-guidelines?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-guidelines/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-guidelines?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-guidelines) -Although structured as any other project in the Gobstones Platform, and containing a `package.json` and other files, this project's focus is documentation of the whole platform. The project is structured as a generated static webpage using `eleventy` ([11ty.dev](https://www.11ty.dev)). The basic structure and styles were copied from the [TypeDoc site](https://github.com/TypeStrong/typedoc-site), although a lot of changes had been done on top of the original source. - --------------------------------------------------------------------- +Although structured as any other project in the Gobstones Platform, and containing a `package.json` and other files, this project's focus is documentation of the whole platform. The project is structured as a generated static webpage using `eleventy` ([11ty.dev](https://www.11ty.dev)). The basic structure and styles were copied from the [TypeDoc site](https://github.com/TypeStrong/typedoc-site), although a lot of changes had been done on top of the original source. + ## About eleventy and the project structure You should not need to know much about `eleventy`, the plugins we use or how the site is structured in order to contribute and write guidelines. Nonetheless you should at least have a grasp of what a **front matter** is, and how it works. -On the root of the project you will find general files, such as `package.json`, `.prettierrc`, `commitlint.config.js` and others, along with the `.husky` and `.github`. If you do not know what they are, you should read the [Technologies](../technologies) section on this same guidelines. +On the root of the project you will find general files, such as `package.json`, `package-scripts.js`, `.prettierrc`, `commitlint.config.js` and others, along with the `.husky`, `.github` and `.vscode` folder. If you do not know what they are, you should read the [Technologies](../technologies) section on this same guidelines. -Beside the aforementioned files, the file `eleventy.config.js` is required for `eleventy` to work. This file holds the configuration of `eleventy` as JavaScript code, and exports a single function, that takes the user configuration object (named `el`) that may be modified as a side effect to add particular requirements to the configuration. The function returns an object, containing mainly the `dir` attribute, specifying the basic directories that `eleventy` will work upon, and the `pathPrefix`, that specifies a possible sub-folder in your hosting. +Beside the aforementioned files, the file `eleventy.config.js` is required for `eleventy` to work. This file holds the configuration of `eleventy` as JavaScript code, and exports a single function, that takes the user configuration object (named `el`) that may be modified as a side effect to add particular requirements to the configuration. The function returns an object, containing mainly the `dir` attribute, specifying the basic directories that `eleventy` will work upon, and the `pathPrefix`, that specifies a possible sub-folder in your hosting (and that we set accordingly to host in **GitHub Pages**). -The code for the site itself is located at the `src` folder. Subfolder `src/templates` contains the basic structure of the site that `eleventy` will use when generating the static pages to be served, while the folders `src/css`, `src/img` and `src/js`, along with the file `src/favicon.ico` are static content that will be served in the site, and compose the site's style. +The code for the site itself is located at the `src` folder. Subfolder `src/templates` contains the basic structure of the site that `eleventy` will use when generating the static pages to be served, that is, the basic HTML templates. The folders `src/css`, `src/img` and `src/js`, along with the file `src/favicon.ico` are static content that will be served on the site, styles (using [Sass styles](https://sass-lang.com) and compiled before served), scripts and images used through the site once it's generated and published. These comprehend the files used for site generation, and make up the site's style and behavior. These file are rarely updated. -If you want to update the guidelines, or contribute new ones, you should only focus on the `Markdown` files (`.md` extension) that live on the `src/pages` folder. Other directories in `src` contain the basic HTML templates, styles, scripts and images used through the site once it's generated and published. The files used for site generation are rarely updated. A special mention should be main to the `.scss` files inside the `src/css` folder. These files contain [Sass styles](https://sass-lang.com) instead of regular CSS, and are compiled before being served as regular `.css` files. +If you want to update the guidelines, or contribute new ones, you should only focus on the `Markdown` files (`.md` extension) that live under the `src/pages` folder and sub-folders. This is the folder that holds the actual content of the site, and they are written in Markdown (If you don't know what Markdown is, you may read [this site](https://www.markdownguide.org)). -The site contents are written in Markdown (If you don't know what Markdown is, you may read [this site](https://www.markdownguide.org)) and they live in the `src/pages` subdirectory and sub-folders within it (sub-folders are there for organizational purposes). If you already know Markdown, you may find strange that the content in those files start with three dashes, contains some content, and then is followed by other three dashes, before containing proper Markdown. Those three dashes and the content inside it (Which is composed of [YAML](https://yaml.org) code) is known as a **front matter**. The following is an example: +If you already know Markdown, you may find strange that the content in those files start with three dashes, contains some content, followed by another three dashes, before containing proper Markdown. Those three dashes and the content inside it (Which is composed of [YAML](https://yaml.org) code) is known as a **front matter**. The following is an example: ```yaml --- -title: About the guidelines - gobstones-guidelines -permalink: /about-guidelines +title: About guidelines eleventyNavigation: - key: About the guidelines + key: About guidelines order: 2 --- ``` The **front matter** provides information to `eleventy` on how to process and publish the page contents of that file. Contents declared in the front matter are used later on in the templates and other places by `eleventy` itself, and also by some plugins, so each expect different information. The ones we use are: + * `title` - A string used as the title of the page -* `permalink` - The relative url to use for accessing this page. * `eleventyNavigation` - An object containing information on how to showcase links to this page in the navigation left sidebar. It includes: * `key` - A string used as text to show as a link. * `parent` - If present, the link will be shown as a sub-element of the parent in the list. * `order` - The order in which the element will be shown on the list or sub-list. -The site's pages usually use the `doc`layout which, besides of a main header, structures the contents in three sections: -* Central section - Contains the contents the page itself, that is, the contents written in the markdown file. -* Left sidebar - Contains the navigation through the site, that is, links to all other pages in the site that declared an `eleventyNavigation` section in their front matter. -* Right sidebar - Contains the navigation through the current page. That is, links that scrolls down the view to a particular heading in the page. All heading declared in the markdown using # symbols are identified and added to the navigation list. +The elements declared in the **front matter** are used when generating the site. Some of these are automatically assigned to all pages in the `eleventy.config.js` file, such as the layout or the permalink, and they may be overwritten by different files, although these is not expected. Regarding the `layout`, by default all pages will use the `doc` layout which, besides of a main header, structures the contents in three sections: + +* **Main content** - Contains the contents the page itself, that is, the contents written in the markdown file. It's presented on the center of the site. +* **Navigation sidebar** - Contains the navigation through the site, that is, links to all other pages in the site that declared an `eleventyNavigation` section in their front matter. It's presented on the left side of the site. +* **Local page navigation** - Contains the navigation through the current page. That is, links that scrolls down the view to a particular heading in the page. All heading declared in the markdown are identified and added to the navigation list automatically. It's presented on the right side of the site. If the need arises to modify the site's structure, styles or scripts, you will need to understand not only the structure, but also the associated technologies. For the most part, you just need to know about Markdown and the **front matter** to be able to modify and add new content. @@ -58,33 +58,31 @@ If the need arises to modify the site's structure, styles or scripts, you will n ## Modifying or adding guidelines contents -As explained in the previous section, contents themselves are stored at `src/pages` in the form of Markdown files. The contain the text to be display on each page, along with a front matter at the top of the content. Those files are the only ones to modify and care about when working with content. +As explained in the previous section, contents themselves are stored at `src/pages` in the form of Markdown files. They contain the text to be display on each page as main content, along with a front matter at the top of the file. Those files are the only ones to modify and care about when working with site guidelines contents. > In this section we will mention `` in some urls. > We refer to the hostname of the page as the location in which -> the site is hosted. For the published site such url is +> the site is hosted. For the published site, such url is > `http://gobstones.github.io/gobstones-guidelines`. While testing > on your local machine, the hostname takes the form of a local url, -> `https:localhost:8080`, and changes in configuration may give -> different host names. +> `https:localhost:8080`. Changes in configuration may give +> different host names, so be sure to understand the implications of possible configuration changes. -If you want to modify the contents of a particular page, then you should open the corresponding file in `src/pages`. Files have a name that matches the url they represent, that is, the file `src/pages/introduction.md` is the one for the url `/introduction`, and -`src/pages/technologies/installation-tutorial.md` is the one for the url `/technologies/installation-tutorial`. +If you want to modify the contents of a particular page, then you should open the corresponding file in `src/pages`. Files are always named `index.md` and live in a folder that matches the url they represent, that is, the file `src/pages/introduction/index.md` is the one for the url `/introduction`, and `src/pages/technologies/technology-list/index.md` is the one for the url `/technologies/technology-list`. -A special mention is worth for the files named `index.md`, which correspond to urls that match the folder in which they are in. That is, the file `src/pages/index.md` corresponds to `/` (the home page), while the file `src/pages/technologies/index.md` corresponds to `/technologies`. Below we explain the decision behind this. +You may wonder why do we use only `index.md` files and folders, and not files with other names. We follow this model as to comply with the idea behind [W3C's Cool URIs don't change](https://www.w3.org/Provider/Style/URI), and so that the files in `src/pages` live in the same location as the HTML generated content on the `./dist` output folder. -As you can observe in all front matters the title of the page is always a semantic title. We expect this title to match the one used as `key` in -`eleventyNavigation`. Also, even though the `eleventyNavigation` can be edited and presented in any way, we expect all content regarding the guidelines, except for this file and the index file, to be a child of `Overview`. The hierarchy of the navigation should match the hierarchy of URLs, that is, the entry for `Installation Tutorial` should be a child of `Technologies`, as the URL for the tutorial is `/technologies/installation-tutorial`, while `Technologies` itself should be a child of `Overview` as, it's url is only `/technologies`. Also, be sure to use a different `order` number than the ones in use, or edit all other numbers accordingly. +As you can observe in all **front matters** the title of the page is always a semantic title. We expect this title to match the one used as `key` in `eleventyNavigation`. Also, even though the `eleventyNavigation` can be edited and presented in any way, we expect all content regarding the guidelines, except for this file and the index file, to be a child of `Overview`. The hierarchy of the navigation should match the hierarchy of URLs, that is, the entry for `Technology List` should be a child of `Technologies`, as the URL for the list is `/technologies/technology-list`, while `Technologies` itself should be a child of `Overview` as, it's url is only `/technologies`. Also, be sure to use a different `order` number than the ones in use, or edit all other numbers accordingly. -If you want to add a new page, is enough to create a new markdown file in the `src/pages` folder or any sub-folder, and start the file with a proper **front matter**. You can copy an existing front matter an edit it for ease, but be sure to properly change all the fields required.Although you can specify any `permalink` in the front matter, we expect the permalink to follow the conventions based on the file name and location. Regarding the `eleventyNavigation` be sure that the navigation also follows on the url convention. +If you want to add a new page, is enough to create a new markdown file in the `src/pages` folder or any sub-folder, and start the file with a proper **front matter**. You can copy an existing **front matter** and edit it for ease, but be sure to properly change all the fields required. Regarding the `eleventyNavigation` be sure that the navigation also follows on the url convention. -**Files and folders naming conventions** +### Files and folders naming conventions -* Use all lowercase filenames and dash (-) as a separator when the file contains multiple words. +* Always name your file `index.md` and place the file in the appropriate folder. +* For folder names, use all lowercase filenames and dash (-) as a separator when the name contains multiple words. * Choose simple 1 or 2 word names instead of long names, that is, prefer `about-guidelines` over `about-the-gobstones-guidelines-project`. -* Use folders and an `index.md` file if there is going to be a highly related content associated to the page you are creating or if the page is likely to have sub-pages. -* Store images and other related assets of a page in the folder of that page, and not in the `src/img` folder, that should contain only element regarding the global template and layout. * Avoid multiple level nesting of folders, preferring only one or two level deep content whenever possible. +* Place a page's related static content into the same folder structure for such a page. That is, an image `something.png` that is going to be used only at `src/pages/architecture/index.md` should be placed at `src/img/architecture/something.png`. --------------------------------------------------------------------- @@ -96,15 +94,25 @@ Although for the most part your markdown will be shown 'as is', so what you mean npm install ``` -Once that is done, you can run the server in local development mode by running +This package uses `nps` as most other **GobstonesWeb2** projects. You can list all possible commands by running: ```sh npm start ``` -This will start the server at `localhost:8080/` which you can access to see the contents. Remember that the actual `pathPrefix` is configured in your `eleventy.config.js`. Currently it's set as `gobstones-guidelines` as this subfolder is used in the remote deployment page in GitHub pages. +To run the local development server and see your changes reflected in the guidelines as a webpage, run: + +```sh +npm start dev +``` -The server will run in watch mode, so every change that you perform to the files will immediately be reflected on the page. +This will start the server at `localhost:8080` which you can access to see the contents. The server will run in watch mode, so every change that you perform to the files will immediately be reflected on the page. + +You can also run tests, which does two things. First, it runs a linter in your markdown files, and next, it verifies that the links (to other files in the site) used in those files are correct. + +```sh +npm start test +``` When the code is committed to the `main` branch of the GitHub repository, a GitHub Action workflow is triggered, `on-commit-publish`. This action automatically publishes the latest changes committed to the `gobstones-guidelines` documentation live page. @@ -113,7 +121,3 @@ When the code is committed to the `main` branch of the GitHub repository, a GitH ## Contributing Just remember to read the full [Contributions Guidelines](https://gobstones.github.io/gobstones-guidelines) to contribute. - - - - diff --git a/src/pages/architecture/index.md b/src/pages/architecture/index.md index 9f44829..4efd394 100644 --- a/src/pages/architecture/index.md +++ b/src/pages/architecture/index.md @@ -6,78 +6,213 @@ eleventyNavigation: order: 3 --- # **Architecture of **GobstonesWeb2**** -The architecture of **GobstonesWeb2** combines several modules providing different functionalities -For each module, there will be a repository in the organization. -The guidelines ask for all repositories to share a basic configuration structure, and in order to ensure it, there is a special module, in repository [gobstones-scripts](https://github.com/gobstones/gobstones-scripts),that all repositories of **GobstonesWeb2** must depend on and be created by, providing the means to automate such sharing. -In this way, when the team decide to change something on the common configuration, all repositories can be easily updated. -The architecture of **GobstonesWeb2** is established by the dependencies between the modules provided by the different repositories belonging to the project, as presented in the following diagram: +The architecture of **GobstonesWeb2** combines several modules providing different functionalities. They all interrelate to conform what is known as the **GobstonesWeb2**, and together with the contents, pedagogic proposals and others conform the **Gobstones Platform**. This section lists all the different modules that compose the architecture, their current status, and how they interrelate. -![GobstonesWeb2 Architecture Diagram](../img/diagram-of-components.svg) +--------------------------------------------------------------------- + +## Basic overview of the architecture + +For each module, there will be a repository in the organization, that is to say, a GitHub project will be present for the module. + +Some modules depend on another, generating a dependency tree. Modules at the bottom of the tree are usually projects that provide utilities and general behavior, while the full application will be at the top of the tree. + +> You may be wondering why we chose a polyrepo approach instead of a +> monorepo one. You may read [A Monorepo vs. polyrepo Summary](https://github.com/joelparkerhenderson/monorepo-vs-polyrepo) +> if you don't know what we are talking about. +> +> In summary, we believe that polyrepo requires simpler tooling, less +> mental effort, and allows for new developers to jump in to a project +> easily. Additionally, not all project of **GobstonesWeb2** are released +> as the same single package. With that in mind, we reached for a +> polyrepo approach, and wrote specialized tooling when needed. + +Som of the modules are currently available or under development, while others are just stubs because they are planned, but no particular release date is yet defined. + +The following is an overview of the projects and their dependencies. + +![GobstonesWeb2 Architecture Diagram](../img/architecture/diagram-of-components.svg) We are currently working in redesigning some of the modules into new grouping. Expect changes on this graphic in the future. -## Details about repositories of GobstonesWeb2 - -
- - Expand full list - -

- The complete list of repositories to be used on **GobstonesWeb2** (either planned or under development). -

- -* [`gobstones-admin-dashboard`](https://github.com/gobstones/gobstones-admin-dashboard), a dashboard for the Gobstones server, -* [`gobstones-assertions`](https://github.com/gobstones/gobstones-assertions), a static and semantic code analyzer for Gobstones language, -* [`gobstones-blocks`](https://github.com/gobstones/gobstones-blocks), a framework agnostic Gobstones Blockly component, -* [`gobstones-blocks-react`](https://github.com/gobstones/gobstones-blocks-react), the REACT layer over gobstones-blocks, -* [`gobstones-board`](https://github.com/gobstones/gobstones-board), a representation for Gobstones boards, -* [`gobstones-board-react`](https://github.com/gobstones/gobstones-board-react), the REACT layer over the gobstones-board, -* [`gobstones-code-editor`](https://github.com/gobstones/gobstones-code-editor), a code editor to use with Gobstones, -* [`gobstones-core`](https://github.com/gobstones/gobstones-core), a set of utility tools used through all GobstonesWeb2 repositories, -* [`gobstones-ide`](https://github.com/gobstones/gobstones-ide), the IDE component, with the actual environment, -* [`gobstones-gbb-parser`](https://github.com/gobstones/gobstones-gbb-parser), a parser/printer for GBB (Gobstones Board) file format, -* [`gobstones-guidelines`](https://github.com/gobstones/gobstones-guidelines), fundamental documentation to contribute to GobstonesWeb2, -* [`gobstones-lang`](https://github.com/gobstones/gobstones-lang), a compiler for Gobstones language, -* [`gobstones-lang-def`](https://github.com/gobstones/gobstones-lang-def), a new module that will replace `gobstones-lang-intl` and `gobstones-parser` (currently not in the diagram). -* [`gobstones-lang-intl`](https://github.com/gobstones/gobstones-lang-intl), translation for Gobstones language built-ins and keywords, -* [`gobstones-lint`](https://github.com/gobstones/gobstones-lint), a linter for Gobstones language, -* [`gobstones-markdown-view`](https://github.com/gobstones/gobstones-markdown-view), a markdown viewer for Gobstones, -* [`gobstones-parser`](https://github.com/gobstones/gobstones-parser), a parser for Gobstones language v3.12, -* [`gobstones-refactors`](https://github.com/gobstones/gobstones-refactors), a refactoring tool for Gobstones language -* [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts), common configuration for all GobstonesWeb2 repositories -* [`gobstones-server`](https://github.com/gobstones/gobstones-server), the Gobstones server, -* [`gobstones-test`](https://github.com/gobstones/gobstones-test), a unit testing framework for Gobstones language, -* [`gobstones-typechecker`](https://github.com/gobstones/gobstones-typechecker), a typechecker for Gobstones language. - -
+Most of the modules share a common structure, regarding files present at the root, the tooling used, how you can work with them, etc. Some files such as the "LICENSE" file, or the ".vscode" folder with recommended add-ons for the Visual Studio Code editor are required to live at the root of every project, but they are actually shared across all the modules. To ensure easy management of this, the [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts) module was created. Most modules in **GobstonesWeb2** depend on the `gobstones-scripts` module. + +--------------------------------------------------------------------- + +## List of Active Projects + +This is the list of projects of **GobstonesWeb2** that are either published under a stable release, or are under active development. + +### ⦿ Gobstones-board + +A representation for Gobstones boards. + +[![Gobstones-board project page](https://img.shields.io/badge/pp-gobstones--board-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-board) [![License](https://img.shields.io/github/license/gobstones/gobstones-board?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-board/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-board?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-board) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-board?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-board) + +### ⦿ Gobstones-board-React + +The React layer over the Gobstones-board. + +[![Gobstones-board-React project page](https://img.shields.io/badge/pp-gobstones--board--react-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-board-react) [![License](https://img.shields.io/github/license/gobstones/gobstones-board-react?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-board-react/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-board-react?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-board-react) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-board-react?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-board-react) + +### ⦿ Gobstones-code-editor + +A code editor to use with Gobstones. + +[![Gobstones-code-editor project page](https://img.shields.io/badge/pp-gobstones--code--editor-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-code-editor) [![License](https://img.shields.io/github/license/gobstones/gobstones-code-editor?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-code-editor/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-code-editor?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-code-editor) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-code-editor?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-code-editor) + +### ⦿ Gobstones-core + +A set of utility tools used through all GobstonesWeb2 repositories. + +[![Gobstones-core project page](https://img.shields.io/badge/pp-gobstones--core-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-core) [![License](https://img.shields.io/github/license/gobstones/gobstones-core?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-core/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-core?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-core) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-core?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-core) + +### ⦿ Gobstones-ide + +The IDE component, with the actual environment. + +[![Gobstones-ide project page](https://img.shields.io/badge/pp-gobstones--ide-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-ide) [![License](https://img.shields.io/github/license/gobstones/gobstones-ide?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-ide/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-ide?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-ide) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-ide?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-ide) + +### ⦿ Gobstones-gbb-parser + +A parser/printer for GBB (Gobstones Board) file format. + +[![Gobstones-gbb-parser project page](https://img.shields.io/badge/pp-gobstones--gbb--parser-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-gbb-parser) [![License](https://img.shields.io/github/license/gobstones/gobstones-gbb-parser`?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-gbb-parser`/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-gbb-parser`?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-gbb-parser`) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-gbb-parser`?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-gbb-parser`) + +### ⦿ Gobstones-guidelines + +Fundamental documentation to contribute to GobstonesWeb2. + +[![Gobstones-guidelines project page](https://img.shields.io/badge/pp-gobstones--guidelines-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-guidelines) [![License](https://img.shields.io/github/license/gobstones/gobstones-guidelines?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-guidelines/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-guidelines?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-guidelines) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-guidelines?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-guidelines) + +### ⦿ Gobstones-lang + +A compiler for Gobstones language. + +[![Gobstones-lang project page](https://img.shields.io/badge/pp-gobstones--lang-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-lang) [![License](https://img.shields.io/github/license/gobstones/gobstones-lang?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-lang/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-lang?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-lang) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-lang?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-lang) + +### ⦿ Gobstones-lang-def + +A new module that will replace `gobstones-lang-intl` and `gobstones-parser` (currently not in the diagram). + +[![Gobstones-lang-def project page](https://img.shields.io/badge/pp-gobstones--lang--def-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-lang-def) [![License](https://img.shields.io/github/license/gobstones/gobstones-lang-def?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-lang-def/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-lang-def?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-lang-def) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-lang-def?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-lang-def) + +### ⦿ Gobstones-lang-intl + +Translation for Gobstones language built-ins and keywords. + +[![Gobstones-lang-intl project page](https://img.shields.io/badge/pp-gobstones--lang--intl-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-lang-intl) [![License](https://img.shields.io/github/license/gobstones/gobstones-lang-intl?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-lang-intl/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-lang-intl?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-lang-intl) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-lang-intl?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-lang-intl) + +### ⦿ Gobstones-markdown-view + +A markdown viewer for Gobstones. + +[![Gobstones-markdown-view project page](https://img.shields.io/badge/pp-gobstones--markdown--view-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-markdown-view) [![License](https://img.shields.io/github/license/gobstones/gobstones-markdown-view?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-markdown-view/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-markdown-view?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-markdown-view) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-markdown-view?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-markdown-view) + +### ⦿ Gobstones-parser + +A parser for Gobstones language v3.12. + +[![Gobstones-parser project page](https://img.shields.io/badge/pp-gobstones--parser-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-parser) [![License](https://img.shields.io/github/license/gobstones/gobstones-parser?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-parser/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-parser?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-parser) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-parser?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-parser) + +### ⦿ Gobstones-scripts + +Common configuration for all GobstonesWeb2 repositories. + +[![Gobstones-scripts project page](https://img.shields.io/badge/pp-gobstones--scripts-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-scripts) [![License](https://img.shields.io/github/license/gobstones/gobstones-scripts?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-scripts/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-scripts?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-scripts) [![API Docs](https://img.shields.io/github/package-json/homepage/gobstones/gobstones-scripts?color=blue&label=API%20Docs&logo=gitbook&logoColor=white&style=plastic)](https://gobstones.github.io/gobstones-scripts) + +--------------------------------------------------------------------- + +## List of Planned Projects + +This is the list of projects of **GobstonesWeb2** that are planned or on the roadmap, but that do not yet have a particular release date, nor anyone is currently working on them. + +### ⦿ Gobstones-admin-dashboard + +A dashboard for the Gobstones server. + +[![Gobstones-admin-dashboard project page](https://img.shields.io/badge/pp-gobstones--admin--dashboard-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-admin-dashboard) + +### ⦿ Gobstones-assertions + +A static and semantic code analyzer for Gobstones language. + +[![Gobstones-assertions project page](https://img.shields.io/badge/pp-gobstones--assertions-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-assertions) + +### ⦿ Gobstones-blocks + +A framework agnostic Gobstones Blockly component. + +[![Gobstones-blocks project page](https://img.shields.io/badge/pp-gobstones--blocks-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-blocks) + +### ⦿ Gobstones-blocks-React + +The React layer over Gobstones-blocks. + +[![Gobstones-blocks-React project page](https://img.shields.io/badge/pp-gobstones--blocks--react-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-blocks-react) + +### ⦿ Gobstones-lint + +A linter for Gobstones language. + +[![Gobstones-lint project page](https://img.shields.io/badge/pp-gobstones--lint-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-lint) + +### ⦿ Gobstones-refactors + +A refactoring tool for Gobstones language. + +[![Gobstones-refactors project page](https://img.shields.io/badge/pp-gobstones--refactors-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-refactors) + +### ⦿ Gobstones-server + +The Gobstones server. + +[![Gobstones-server project page](https://img.shields.io/badge/pp-gobstones--server-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-server) + +### ⦿ Gobstones-test + +A unit testing framework for Gobstones language. + +[![Gobstones-test project page](https://img.shields.io/badge/pp-gobstones--test-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-test) + +### ⦿ Gobstones-typechecker + +A typechecker for Gobstones language. + +[![Gobstones-typechecker project page](https://img.shields.io/badge/pp-gobstones--typechecker-blue?style=plastic&label=Repository&logo=github&logoColor=white)](https://github.com/gobstones/gobstones-typechecker) + +--------------------------------------------------------------------- ## Repositories configuration -The [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts) module is used to create other modules for the [GobstonesWeb2] platform, and to abstract away configuration details in all the projects. +The [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts) module is used to create other modules for the **GobstonesWeb2** platform, to abstract away configuration details in all the projects and to maintain a common structure of files in all repositories, thus, partially aiding the polyrepo approach and helping in the scaffolding process. + +The module can be used as a command line program that allows to create new modules, through the subcommands `create` or `init`. It provides several templates for different types of projects, such as creating simple libraries, command line applications that can be also used as libraries, React components, simple web components, and others. + +Most of the project's created require tools such as `typescript`, `rollup`, `nps`, `jest`, `typedoc` and others. In that sense, the modules created do not have direct dependencies for all those tools in their declaration file (`package.json``), instead having a dev-dependency only on`Gobstones-scripts`, which in itself have the dependencies on the tools. This allows for a centralized version management of all the tooling, that can be easily overwritten if needed by any project by just adding a different version of the tool into their own declarations. -The module can be used as a command line program that allows to create new modules, through the subcommands `create` or `init`. It provides several template for projects, such as creating simple libraries, command line applications and libraries, react components, and simple web components. +Some configuration files needed by the tooling, such as `tsconfig.js` or `rollup.config.js`, are abstracted away by the `gobstones-scripts` module, which holds the configuration files. This allows for a less cluttered root for the projects, and also to centralize the process of building, style of the documentation, etc. In case some project requires a particular configuration, these configuration files can be overwritten in the projects, by the subcommand `eject`, which will copy the abstracted files to the project root. -The project's created have tools such as `typescript`, `rollup`, `nps`, `jest`, `typedoc` and others a development dependencies. In that sense, the modules created do not have direct dependencies for all those tools, having a dev-dependency only on `gobstones-scripts`, which in itself have dependencies on the tools. In that sense the module assumes a flat `node-modules` organization. +Other configuration files for some tooling, such as `.prettierc` used by `prettier`, or `.eslintrc` used by `ESLint`, are required unfortunately to be in the project root, as editors such as Visual Studio Code or others expect to find the declaration file in order to provide meaningful hints, code completion and refactoring. This files are usually all the same for every project, and it's cumbersome to create and maintain them all. The `gobstones-scripts` package generate those files when creating new project and can help maintain the same version through the different project through the `update` command, that updates those files if needed. Changes to the files can be made tgo provide customization if any project requires it. -Some configuration files needed by the tooling, such as `tsconfig.js` or `rollup.config.js`, are abstracted away by the `gobstones-script` module, which holds the configuration files. These configuration files have a default version, but, in case some module requires a particular configuration, these configuration files can be overwritten in the projects, by the subcommand `eject`. +Finally, mot projects will require to execute scripts as to automate processes that help in the development, such as starting up a development server, build the project, generate the documentation webpage, run the tests and so on. We make use of `nps`, a task runner that is elegant in it's simplicity. This tool provides just one step over the simple `scripts` section of a `package.json` file, but allowing to declare the scripts into a separate file, usually called `package-scripts.js`. The tool also provides things such as listing the commands, print help, etc. When executing scripts from `nps`, many tools will expect to find the configuration files in the root of the project, instead of the abstracted configuration files provided by `gobstones-scripts`. To make it easy to run and execute the tooling, `gobstones-scripts` provides the `run` subcommand, that executes `nps` commands, but loading the configuration for each tool from the appropriate location (considering also that it may be abstracted, overwritten by the user, etc.). -Other configuration files for some tooling, such as `.prettierc` used by `prettier`, or `.eslintrc` used by `ESLint`, are automatically created in the root of the created projects. Those files may require some sort of update as versions of the tooling are updated, or changed, and for that, the subcommand `update` allows for updating such files. +Alongside the `run` command, the `gobstones-scripts` module may be used as a library, from which you may obtain the `tasks` object. This object is useful if you so decide to `eject` the configuration file for `nps`, as it provides a simpler way to execute the most common tools, such as `rollup` or `typescript`, and even other `nps` commands, running tasks in parallel or serially, etc. -Finally, the tool allows to run different actions defined through `nps`, by running the `run` subcommand. +You can read more about the `gobstones-scripts` project in the [`gobstones-scripts`' repository](https://github.com/gobstones/gobstones-scripts). If you want to know more about the different configuration files and tooling we use, you can read about it in the [Technologies Section](../technologies). -You can read more about the tool, configuration files, and tooling in the [Technologies we use](../technologies) section. +--------------------------------------------------------------------- ## Basic functionalities Another useful project is [`gobstones-core`](https://github.com/gobstones/gobstones-core), that provides some basic utilities used through different projects. -The project includes things such as the idea for `Event`'s that have typechecking, for throwing events that objects an subscribe to, and some particular data structures or types, such as `BiMap` or `Subset`. +The project includes things such as the idea for `Event`'s that have typechecking, for throwing events that objects can subscribe to, and some particular data structures or types, such as `BiMap` or `Subset`. -Another utility provided is the `Expectations` module, that allows for setting up expectations to validate user inputs and other stuff. +Another utility provided is the `Expectations` module, that allows for setting up expectations to validate user inputs and data. -The `SourceReader` module provides a class that allows to provide source files and process them as a stream, reading one or more character at a time. This is useful for tokenizing inputs. +The `SourceReader` module provides a class that allows to read code agnostic source files and process them as a stream, reading one or more character at a time. This is useful for tokenizing inputs. -This module is required by default in projects created by `gobstones-scripts`, and is required by most projects in used in [GobstonesWeb2]. +This module is required by default in projects created by `gobstones-scripts`, and is required by most projects in used in **GobstonesWeb2**, although it's usage is not mandatory at all. -You can read more about the things the module exports in the [`gobstones-core's README`](https://github.com/gobstones/gobstones-core). +You can read more about the things the module exports in the [`gobstones-core`'s repository](https://github.com/gobstones/gobstones-core). diff --git a/src/pages/coding-standards/coding-contributor/index.md b/src/pages/coding-standards/coding-contributor/index.md deleted file mode 100644 index bdbd520..0000000 --- a/src/pages/coding-standards/coding-contributor/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Coding Contributor -eleventyNavigation: - key: Coding Contributor - parent: Coding Standards - order: 5 ---- diff --git a/src/pages/coding-standards/coding-team/index.md b/src/pages/coding-standards/coding-team/index.md deleted file mode 100644 index d95dfb4..0000000 --- a/src/pages/coding-standards/coding-team/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Coding Team -eleventyNavigation: - key: Coding Team - parent: Coding Standards - order: 5 ---- diff --git a/src/pages/coding-standards/documentation/index.md b/src/pages/coding-standards/documentation/index.md deleted file mode 100644 index 4484efe..0000000 --- a/src/pages/coding-standards/documentation/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Documentation -eleventyNavigation: - key: Documentation - parent: Coding Standards - order: 5 ---- diff --git a/src/pages/coding-standards/index.md b/src/pages/coding-standards/index.md deleted file mode 100644 index 2ba50f5..0000000 --- a/src/pages/coding-standards/index.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Coding Standards -eleventyNavigation: - key: Coding Standards - parent: Overview - order: 5 ---- -# Coding standards and workflow for **GobstonesWeb2** - -If you are going to start developing code you need to understand how projects are organized, how to push code, and what coding standards we use. If you are joining the **Core Team**, or are planning to collaborate as an external developer, you should be sure to understand this section fully. - -## Project organization - -You should first understand how our projects are organized, what files are there, and what are they for, and how we organize different files in folders. Be sure to read the [**Project organization**](./project-organization) section before starting. - -## Naming conventions - -No guideline is complete without a proper way to explain how the names of files, variables, classes and others is chosen. Please be ure to read the [**Naming conventions**](./naming-conventions) section before going any further. - -## Workflow - -You now understand how projects are organized, great, now what? How do I add new features or correct new bugs? We have detail steps on how to contribute, depending on who you are. If you are an external developer, wanting to contribute to the project, please read the [**Coding as an External Contributor**](./coding-contributor) section. If you have join the **Core Team**, pleade be sure to read the [**Coding as a Team Member**](./coding-team) section. -In either case you should read about [**Commit conventions**](./commit-conventions). - -## Testing - -No contribution or work can be properly finished without proper testing. We use `Jest` to test our code, but we a special way of writing tests altogether. Please be sure to read the section dedicated to [**Testing**](./testing) in order to understand how we write tests. - -## Documentation - -And of course, if you contribute new code, it has to be documented properly. Please read the section dedicated to [**Documentation**](./documentation) before sending any pull request. - - -### Module creation - -**TO BE DONE:** how to create a module - -### Module cloning -In order to start working on a module, you first has to clone it to your local machine. -Then you run - - npm install - -in order to install the different packages the module uses. - -### Working on an issue -If you want to work on an issue on the package, and it is not already in the issue-tracker, -create the new issue in the organization as your first step. -You must take care of: - * defining the right assignees and labels, - * associating the issue with the corresponding project, and - * giving the right status to the issue (usually: _"Todo"_). -Be also sure of give the issue a proper name and to describe the tasks required. - -Once the issue is on the issue-tracker, its status is _"Todo"_, and it was not assigned to someone else: - * assign the issue to yourself, - * change the status to _"In Progress"_, and - * create a branch for the issue. - -In your local clone checkout the new issue-branch, and work on the change. -When committing, in the message describe briefly the things you modified. - -When you finish your changes, and before doing a pull-request, you must: - * be sure all tests pass, and the test coverage is enough - - npm run test - - * generate the documentation, taking care that no warnings for wrong links are produced - - npm run doc - - * build your module. - - npm run build - -After that, you made the pull-request, and ask for revision. -Remember to indicate in the pull-request subject that it closes the corresponding issue, and change the status of the issue to _"Requested for revision"_. - - - -## **TO BE DEVELOPED:** Notes to write about -About Github flow. -https://docs.github.com/en/get-started/quickstart/github-flow -The only exception is that merging of branches is done by the Technical Committee. -Will we use it? - -Document all your code using [Typedoc](https://typedoc.org/guides/overview/), and generate the documentation. - -Please follow this conventions for filenames. - * Names should be descriptive and in english. - * All lowercase with kebab-case should be used for filenames, with no spaces - (Except README, CONTRIBUTING and LICENSE that are all uppercase). - * Only use CamelCase for classes in TS, not documentation files. - - Kebab case -- or kebab-case -- is a programming variable naming convention where a developer replaces the spaces between words with a dash. - Programming variable names should be descriptive. - -_< TO BE DONE: expand >_ diff --git a/src/pages/coding-standards/naming-conventions/index.md b/src/pages/coding-standards/naming-conventions/index.md deleted file mode 100644 index 3abe7c1..0000000 --- a/src/pages/coding-standards/naming-conventions/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Naming Conventions -eleventyNavigation: - key: Naming Conventions - parent: Coding Standards - order: 5 ---- diff --git a/src/pages/coding-standards/project-organization/index.md b/src/pages/coding-standards/project-organization/index.md deleted file mode 100644 index 9f1183b..0000000 --- a/src/pages/coding-standards/project-organization/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Project Organization -eleventyNavigation: - key: Project Organization - parent: Coding Standards - order: 5 ---- diff --git a/src/pages/coding/code-styling/index.md b/src/pages/coding/code-styling/index.md new file mode 100644 index 0000000..3628fab --- /dev/null +++ b/src/pages/coding/code-styling/index.md @@ -0,0 +1,120 @@ +--- +title: Code Styling +eleventyNavigation: + key: Code Styling + parent: Coding + order: 2 +--- +# Code Styling + +In big open source project's is difficult to allow multiple people contribute letting everyone have their own style. Thus, we try to enforce many styling conventions in out projects, as well as make use of some design patterns, as to make the experience of coding more pleasant to everyone. + +--------------------------------------------------------------------- + +## Code style + +For the most part, we try to follow the [Styleguide from the TypeScript Book](https://github.com/basarat/typescript-book/blob/master/docs/styleguide/styleguide.md), but we find some of the recommendations vary relaxed or simply not fittable to our project and processes, so we follow the guide with some modifications. In this section we will discuss most of the styling changes we adopted, but we expect you to be familiar with the language and the aforementioned styling guide. + +You will find also that many of the styling rules are enforced by the linter, thus, ending in an error when attempting to run the same (which is done a the first step of our testing process). + +### Variables, Parameters, Functions and Method names + +We use `camelCase` for all our variables, parameters, functions and method identifiers, for the most part. We have some particular cases needed to be considered. + +We expect you to use the appropriate visibility modifiers, either `private`, `protected` or `private` in class methods and attributes. In non class elements, remember that each file is treated a module on their own, so only exported members will be visible. TypeScript does not provide a module/package level visibility modifier, but you can mark a particular element as internal through the use of documentation. By default, the TypeScript compiler configuration we use will strip all internal elements so they cannot be used by third party users of our library. + +```ts +/** @internal */ +public doSomething() { + return name; +} +``` + +By making use of this, and the Barrel Pattern, you can ensure that package level elements only live withing the expected sub-modules. + +Although the [Underscore Dangle](https://eslint.org/docs/latest/rules/no-underscore-dangle) is discouraged in today's standards for the most part, we do tend to use it in some places. + +An undercore identifier can be used to reflect that a variable or parameter is not relevant (e.g. after a destructuring assignment, or when multiple parameters are expected in callbacks or similar cases). + +Also, some of our code do use underscore dangles in their names for private or protected level fields, with a single underscore at the beginning to reflect the visibility level. + +### Class, Interfaces, Types, Enums and Namespace + +For all, use `PascalCase` as per stated in the book. Do not use prefixes such as "I" for interfaces, or suffixes like "Impl" for concrete classes (e.g. avoid names like "IEnumerable" or "StackImpl"). + +Do use the "Abstract" word in some part of the name when defining abstract classes, when on complex multiple level hierarchies (e.g. do use "AbstractSourcePosition" instead of "SourcePosition" if the hierarchy is complex). + +We prefer interfaces over types when describing type that are composed of properties only. Also, do use interfaces over classes to decouple implementation when the interface i one of the main parts of the API exposed. + +In the case of classes that represent runtime error, use the "Error" as a suffix (e.g. `InvalidUserInputError`). + +Names for classes, interfaces, types and enums should be singular, except for the case of utility classes. + +### Formatting and spacing + +For the most part, we use the formatting described in the book, leaving a space before and after expression symbols, using only single quotes whenever possible and recurring to double quotes only for cases when there is a single quote character as part of the string. + +Semicolons are mandatory and we make use of `===` comparison, instead of simple `==`. + +Regarding spacing, we make use of 4 spaces instead of 2. + +### Filenames + +We use the following conventions: + +* If your file exposes a single class, name the file as the class, using `PascalCase` (e.g. `DataReader.ts`) +* If your file exposes a single function, name the file as the function, using `camelCase` (e.g. `isEmptyArray.ts`). +* If your file exposes multiple elements, use `kebab-case` (e.g. `string-utils.ts`). +* React components are always named after the component, thus, using `PascalCase` (e.g. `ContactCard.tsx`). +* React components adjacent file (such as the component style or similar) should be name as per the component (e.g. `ContactCard.scss` if the component is named `ContactCard.tsx`). +* Folders should be named with similar regards. If the folder exposes a module with multiple elements, use `kebab-case`, but if it "mainly" exposes a single class or function, use `PascalCase` or `camelCase`. +* In the case of React components, use a folder per component, with the name of the component in `PascalCase`. + +--------------------------------------------------------------------- + +## Design patterns + +We also make use of ome design patterns as to organize our code in a simple, effective and easy to expect manner. We recommend that you read [the TypeScript Book tips section](https://github.com/basarat/typescript-book/tree/master/docs/tips) that explains many patterns that we do follow, their whys and shortcomings. + +### Barrel pattern + +The **barrel pattern** it's a common organizational pattern in JavaScript and TypeScript. It consists of adding an `index.js` or `index.ts` (we will use this one, as we use TypeScript) in each folder. This transforms the folder itself into a module. Then, instead of having to import the individual files of the folder, you import the folder itself. + +The `index.ts` file is in charge of also orchestrating the elements exposed from that module, by re-exporting elements, or generating a cohesive folder that exposes everything. + +This pattern is really useful and allows for isolation of sub-modules even from inside a project itself. Consider the case where inside a folder of a project there are multiple files, each exposing multiple things, like classes and functions. Each file is required to expose all those elements, because other files inside the folder do import and make use of those elements. However, some of those functions and classes are not expected to be used from outside the folder itself (we want to have package/module level visibility). But users can always import any file, and use any function, because they have to be public in order to be used from within other files. The `index.ts` file inside the folder will expose only the functions and classes that are actually expected to be used from outside of the folder. Used of the elements inside the folder are expected to always import the folder itself, and not the individual files. Although the pattern does not enforce visibility, it does generate a usage expectation, thus clearly marking boundaries of different folders, each acting as a sub-module inside the same project. + +We make heavy use of the Barrel pattern in all of our projects, and we encourage following the same. + +### Use of property setters and getters + +The tips section of the TypeScript book says that using the property setters should be limited, possibly because a lot of people do ue this feature erroneously. Knowing when to use a variable, which visibility to give, and when to ue the property getters and setters is not alway easy if you come from other languages, so this section expects to be a guide to newcomers, and also shed some light on the decisions we take when exposing attributes. + +* If a property is read-write and no special actions should be taken when such an event happens, use a `public` access attribute instead of a private variable with public getter and setter. This is easier, reduces code, and can always be modified in the future. +* If you want a readonly property, use the `readonly` modifier on a public variable whenever possible. You may find that this is possible most of the times, except in cases where the variable does need to be modified internally, in which case, follow the next point. +* Use property getters to expose read-only variables that cannot be `public readonly` as they require internal modification after some actions. +* Use property getters to expose simplify the API if desired, as to expose elements that are immutable in context, and that may be obtained by other means, but are uncomfortable to do so in code (e.g. `get last() { return this.elementAt(this.length -1); }`). +* Do NOT use property getters for elements that are CPU or memory intensive or require hard calculations. Use a method instead. +* Property setters should only be used when there is an associated private variable (or multiple variables that do change in a simple expected manner). If there is an associated getter, then calling the getter, after the setter had been used, should retrieve the same value used with the setter. +* Property setter should only modify the associated object and should modify other objects. They should not have side effects. +* Use property setters only in cases where: + * Before changing the associate private variable, some validations should be performed as to throw custom errors. + * The action of setting the variable should be logged. + * An event should be thrown after changing the value. + +### Constructors + +Classes in TypeScript only allow one constructor. Some people coming from other languages also find this problematic. Here are some patterns to follow when working with constructors and initializing objects. + +* Only define a constructor if your class expects initialization values, otherwise, do not define a constructor (do not define empty constructors). +* If your class do not expect external initialization values, but some initial values should be provided to some internal private attributes, set the values at definition time, and avoid defining a constructor. +* If your class expects some initialization values that will match some attributes, use the attribute definition shortcut in the constructor, thus, defining the attributes in the constructor itself. +* If your constructor expects a big configuration, expect an object holding the configuration, instead of endless parameters. Unless really needed, avoid really deep configurations, and rely on one level objects. + +--------------------------------------------------------------------- + +## Others + +This are the basic idea behind our styling, and as mention, some of this rules are enforced, while others are left to you. If you are in doubt about the style to use, first let the linter tell you, read exiting code to see the style used, and if no answer arises, ask to the core team what style should be best fit for such a particular problem. + +Also, note that some particular elements, such as tests and documentation have their own styling expectations. Read the [Testing Section](../testing/) or the [Writing Documentation Section](../writing-documentation) to know more about it. diff --git a/src/pages/coding-standards/commit-conventions/index.md b/src/pages/coding/commit-conventions/index.md similarity index 80% rename from src/pages/coding-standards/commit-conventions/index.md rename to src/pages/coding/commit-conventions/index.md index 5c58038..a8c7d94 100644 --- a/src/pages/coding-standards/commit-conventions/index.md +++ b/src/pages/coding/commit-conventions/index.md @@ -2,24 +2,24 @@ title: Commit Conventions eleventyNavigation: key: Commit Conventions - parent: Coding Standards - order: 5 + parent: Coding + order: 3 --- # Commit conventions of the **GobstonesWeb2** projects We have decided to embrace [GitHub Flow](https://githubflow.github.io) with some modifications, as well as [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) in all our projects. This section describes such conventions and will help you to understand how to work in a collaborative environment in the **GobstonesWeb2** projects. ------------------------------------------------------ +--------------------------------------------------------------------- ## GitHubFlow and our branches model -**GitHub Flow** is a lightweight workflow for team collaboration using `git`. You don't actually need to be using `GitHub` to follow it, it just happens that we use it also. If you have work with other workflows, such as **git-flow**, you will find **GitHub Flow** a breeze to work on. +**GitHub Flow** is a lightweight workflow for team collaboration using `git`. You don't actually need to be using `GitHub` to follow it, it just happens that we use it also. If you have work with other workflows, such as **Git-flow**, you will find **GitHub Flow** a breeze to work on. We recommend you to read the official page at [GitHub Flow](https://githubflow.github.io) to know a little bit of the reasons behind why **GitHub Flow** exists and what is the main idea behind it. Nonetheless, the following is a breakdown of our takeout in the workflow. * We have a branch named **main** at every project. That branch contains deploys or is deploy ready. * **main** is protected (on stable projects) and you cannot commit to main branch directly. -* We do not make continuous deployment with the **main** branch, but we do produce tags based on main with deployments, named **v**. +* We do not make continuous deployment with the **main** branch, but we do produce tags based on main with deployments, named **v< semVer >**. * Every other branch besides **main** contains ongoing work by one or more members of the core team. * When working on a new feature, bugfix or hotfix, a new branch should be created. All development of the feature or bugfix should happen in that branch. We call these **feature branches**. * All commits to a **feature branch** are temporal, and you can commit in any way you please, as long as you do not perform a **pull request**, you can even perform partial commits. @@ -29,34 +29,37 @@ We recommend you to read the official page at [GitHub Flow](https://githubflow.g * The **feature branch** should then be deleted from the central repository to avoid overhead of branches when managing the repository. Be sure to: + * Always create a **feature branch** based on **main**. * Only start the development of a feature or bugfix after discussing that you are going to do it, to avoid multiple people working on the same issue. ------------------------------------------------------ +--------------------------------------------------------------------- ## Realeases -We make use of [Semantic Versioning 2.0.0](https://semver.org) format to label our releases. That is, three numbers separated by dots that comply with the ".." format, so that they update in the following way: +We make use of [Semantic Versioning 2.0.0](https://semver.org) format to label our releases. That is, three numbers separated by dots that comply with the "< MAJOR >.< MINOR >.< PATCH >" format, so that they update in the following way: + * MAJOR version when you make incompatible API changes. * MINOR version when you add functionality in a backward compatible manner. * PATCH version when you make backward compatible bug fixes. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. -As long as "" is "0" we consider the releases to be a **initial development** and as such, major changes in the API may occur in any version change. Once a stable version is ready (the team will decide upon it) a 1.0.0 version will be published, and API is expected to be backwards compatible as long as "" don't change. +As long as "< MAJOR >" is "0" we consider the releases to be a **initial development** and as such, major changes in the API may occur in any version change. Once a stable version is ready (the team will decide upon it) a 1.0.0 version will be published, and API is expected to be backwards compatible as long as "< MAJOR >" don't change. -Releases are automatically performed when a tag on the **main** branch is created with a name that matches **v**, where "" is a semantic versioning number. Creating such a tag releases the version in several platforms, updates the documentation, and more. For this, tags in the repository should only be managed by internal members of the team, and you should not attempt to create tags on any project. +Releases are automatically performed when a tag on the **main** branch is created with a name that matches **v< semVer >**, where "< semVer >" is a semantic versioning number. Creating such a tag releases the version in several platforms, updates the documentation, and more. For this, tags in the repository should only be managed by internal members of the team, and you should not attempt to create tags on any project. Although we do not perform continuous deploy, we do perform a deploys regularly, a we expect that **GobstonesWeb2** takes the form of a rolling release on the web. That is, we do not expect to have multiple versions of **GobstonesWeb2** deployed at the same time, but always have the latest version as the deployed one. ------------------------------------------------------ +--------------------------------------------------------------------- ## Commit messages and changelog -We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) in our commit messages. This is desirable so changes in code can be traced through the development process in the git tree. This also ensures that we can easily create a `CHANGELOG` file stating contributors and all important changes. +We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) in our commit messages. This is desirable so changes in code can be traced through the development process in the Git tree. This also ensures that we can easily create a `CHANGELOG` file stating contributors and all important changes. The basic idea behind conventional commits is that commit messages should convey meaning, and thus, should follow a particular structure. The basic structure is: + ``` [optional scope]: @@ -64,8 +67,10 @@ The basic idea behind conventional commits is that commit messages should convey [optional footer(s)] ``` + The `type` is meant to explain what the main purpose of the commit is, and may be any of: + * **feat**: a commit that introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning). * **fix**: a commit that patches a bug in your codebase (this correlates with PATCH in Semantic Versioning). * **docs**: a commit that only adds or fixes documentation. @@ -78,16 +83,16 @@ The `type` is meant to explain what the main purpose of the commit is, and may b If a commit creates incompatible changes with the existing API, that is, it makes the code non backwards compatible, you should add a **BREAKING CHANGE** footer, and in that case, add a description of what changed in your body. -The `scope`` should be used in case where there are clearly defined submodules in the system, and your code affects only one of such modules. The `description` should be no longer than 80 characters, and be as clear and concise as possible. Use the `body` to further explain the meaning of the commit if needed. +The `scope`` should be used in case where there are clearly defined submodules in the system, and your code affects only one of such modules. The`description` should be no longer than 80 characters, and be as clear and concise as possible. Use the `body` to further explain the meaning of the commit if needed. Ideally, you are creating code because you have previously stated the work to be done to the rest of the team and the community, and as such, there is a corresponding **Issue** in the project assigned to you. In such a case, you should state in your commit message that the commit resolves a particular feature, or fixes a particular bug. This is achieved by using the word `fix` followed by a hah and the number of the issue being solved (e.g. `fix #71`). Do use this convention in order to automatically close issues and simplify development process. The projects of **GobtonesWeb2** enforce the use of conventional commit through various tools in the development process, such as **Commitizen**, **CommitLint** and **Conventional Changelog**. This tools are triggered automatically through **Git Hooks** as explained in the next section. ------------------------------------------------------ +--------------------------------------------------------------------- ## Git Hooks -**Git Hooks** are a way to trigger automatic actions when a git action is performed. We achieve this using the amazing [Husky](https://typicode.github.io/husky). +**Git Hooks** are a way to trigger automatic actions when a Git action is performed. We achieve this using the amazing [Husky](https://typicode.github.io/husky). **Husky** triggers actions stored in the `.husky` folder at the root of the project. diff --git a/src/pages/coding/index.md b/src/pages/coding/index.md new file mode 100644 index 0000000..0ea79a4 --- /dev/null +++ b/src/pages/coding/index.md @@ -0,0 +1,48 @@ +--- +title: Coding +eleventyNavigation: + key: Coding + parent: Overview + order: 5 +--- +# Coding standards and workflow for **GobstonesWeb2** + +If you are going to start developing code you need to understand how projects are organized, how to push code, and what coding standards we use. If you are joining the **Core Team**, or are planning to collaborate as an external developer, you should be sure to understand this section fully. + +--------------------------------------------------------------------- + +## Project Organization + +You should first understand how our projects are organized, what files are there, what are they for and how we organize different files in folders. + +Be sure to read the [**Project Organization Section**](./project-organization) before starting. + +--------------------------------------------------------------------- + +## Code Styling + +No guideline is complete without a proper way to explain how the names of files, variables, classes and others is chosen. + +Please be sure to read the [**Code Styling Section**](./code-styling) before going any further. + +--------------------------------------------------------------------- + +## Submission Workflow + +You now understand how projects are organized and how the code should be styled great, now what? How do I contribute by adding new features or correcting bugs? How do I submit code? + +The first step is to get acquainted with the workflow we use to manage our code. Be sure to read the [**Commit Conventions Section**](./commit-conventions). + +Then, you can see detailed instruction on how to contribute by getting assigned to a task, and producing code. Read the [**Submission Workflow Section**](./submission-workflow) to know more about it. + +--------------------------------------------------------------------- + +## Testing + +No contribution or work can be really finished without proper testing. We use **Jest** to test our code, but we have a special way of writing tests altogether. Please be sure to read the [**Testing Ssection**](./testing) in order to understand how we structure our tests. + +--------------------------------------------------------------------- + +## Documentation + +And of course, if you contribute new code, it has to be documented properly. Please read the [**Writing Documentation Section**](./writing-documentation) and be sure to properly document everything before sending any pull request. diff --git a/src/pages/coding/project-organization/index.md b/src/pages/coding/project-organization/index.md new file mode 100644 index 0000000..98eb6db --- /dev/null +++ b/src/pages/coding/project-organization/index.md @@ -0,0 +1,165 @@ +--- +title: Project Organization +eleventyNavigation: + key: Project Organization + parent: Coding + order: 1 +--- +# Project Organization + +The first thing to understand is how projects are organized in terms of the file system, that is to say, get to know which files are there and what are they for. + +Most of the **GobstonesWeb2** projects will be comprised of multiple files, and their organization will be explained in the corresponding `README.md` file. This document will explain the most common configurations. + +Most of the projects that work as libraries are created from the [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts) project. That is, the structure of the project is based on one of the provided project structures of `gobstones-scripts`, in either one of: + +* library +* cliLibrary +* reactLibrary +* webLibrary +* nonManaged + +Other projects that work as full fledge React applications are created using [`create-react-app`](https://create-react-app.dev) while backend manager is created using [`payload`](https://payloadcms.com). Other more strange projects may exist, like this [guidelines project](../../about-guidelines/). + +Some files though are general for any project. We will divide this section in parts where we will explain each + +--------------------------------------------------------------------- + +## Files in different projects + +### Files present in all projects + +Some files are present in every **GobstonesWeb2** project. + +All projects are based on `TypeScript`/`JavaScript` technologies, so they will all contain a `package.json` file. This file will contain information such as the package name, version and description, the repository and webpage, author information, exported information and dependencies. + +Another file that will be present every time is the `README.md` file. This file contains information about the project itself, such as the project name and full description, how to install it and use it, how to develop and contribute to the project further on, and other useful information. + +An additional file present at the root of the project is the `LICENSE` file, which contains the software license of the project. In most cases, this is the **AGPL** license version 3. + +The `CONTRIBUTING.md` file holds information on how to contribute to the project. + +The `CHANGELOG.md` file holds information of all the versions and changes to the project. + +The `.gitignore` will also be an ubiquitous file that holds the information of folders and projects not to commit to the central repository. + +Additionally to this files, you will find the files `.prettier` and `.prettierignore`, that holds the prettier configuration for the project files, along with the `.editorconfig` file, that does a similar thing. + +You will also find the `.czrc` file, that hold the **[commitizen](../../technologies/technology-list/#commitizen)** information, and the `commitlint.config.js` that holds the **[commitlint](../../technologies/technology-list/#commitlint)** configuration. + +Regarding folders, you will find the `.github` folder, that holds pull reques templates, issue templates and most importantly, the GitHub Action workflows. Also the `.husky` folder will hold the Git Hooks triggers in use. Finally the `.vscode` folder holds the add-ons and configuration that Visual Studio Code should use when opening this project. + +Finally, code or important files will live in the `src` folder, while testing files will live at the `test` folder. + +As a summary, we will find: + +* `package.json` +* `README.md` +* `LICENSE` +* `CONTRIBUTING.md` +* `CHANGELOG.md` +* `.gitignore` +* `.prettier` +* `.prettierignore` +* `.editorconfig` +* `.czrc` +* `commitlint.config.js` +* `.github` +* `.husky` +* `.vscode` +* `src` +* `test` + +### Usual generated folders + +Some folder's might act as generated folders in multiple (but not all) projects, and they are not present by default, but appear after a particular action had been executed in the project. + +One of this is `node_modules` that appears when the dependencies are installed, `dist` that will usually hold the generated files after building, `doc` that will hold documentation generated by a particular tool, or even `coverage` that holds the testing code coverage for multiple projects. + +This projects will not be added or uploaded to the central repository. + +A summary of this includes: + +* `node_modules` +* `dist` +* `doc` +* `coverage` + +### libraries and CLI libraries project files + +The projects that are intended to be published as simple libraries or cliLibraries will usually contain a `.eslintrc.js` file that contain the configuration to **ESLint**. + +The `.npmignore` file will hold configuration on which elements to publish, that is, which files will be present when someone downloads the library to use it. + +Present files increase with: + +* `eslintrc.js` +* `.npmignore` + +Regarding the code, you will find TypeScript (`.ts` extension) files inside both the `src` and `test` folders, with a `src/index.ts` that acts as a Barrel Pattern containing the main element to expose when someone wants to use the library through the API. In the case of CLI applications, you will also find a `src/cli.ts`, that holds the application that will be executed when running the library as a CLI application. + +Inside the `src` folder, you may find multiple sub-folders, each one holding a sub-module or sub-section of the library. Each of this will contain one or more TypeScript files. In each folder you will find an `index.ts` file, that acts as an entry point of the submodule, holding the sub-module documentation and exports, following the Barrel Pattern. + +In the `test` folder you may find the same folder structure that in the `src` folder, containing test files, either unit test or functional tests, ending in `.test.ts`. + +The rest of the configuration of the project will be abstracted away through the use of `@gobstones/gobstones-scripts`, except that the project ejected any of the configuration files for customization. You will find the configuration for the library at the `package.json` file's `config.gobstones-scripts` key. + +### React libraries project files + +React libraries are also created through `@gobstones/gobstones-scripts` and so will share the abstracted files, tool configuration at `package.json` and project structure as libraries and CLI libraries. + +Additionally to those files, you will find at the root of your project a `vite.config.js` file, that configures Vite to run your storybooks, for easy development and documentation through the tool. An additional `.storybook` folder will contain the StoryBook configuration, while the `stories` folder will contain all stories. + +In this projects, the main sub-folder at `src` is `components` that will hold all the project components. Each component is stores in a folder inside `src/components`, that has a pascal case name, and contains all files for such component, including code (in the form of a `.tsx` file), styles (using Sass) and other assets. + +### React applications project files + +The main applications that we use are mostly React based, and they were scaffolded using the popular Create React App tool. The tool provides a specific tooling set for applications, including Webpack and others. We have chosen this as it's a proven and stable environment for React applications. + +On top of the original scaffolding, we have added some additional files and tooling, and changed some of the default scripts in `package-json` as to match the ones used by the rest of the **GobstonesWeb2** projects. So you can expect `gobstones-scripts` to be present in this projects also. + +--------------------------------------------------------------------- + +## Common `package.json` organization + +As we stated, `package.json` is one of the most important files in any project, as it contains the information of the project (name, version, author, etc.) and also contains the `scripts` section, which contains common tasks that can be executed to achieve certain goals. In our project we attempt to maintain a common set of script actions. + +The first one you will find is the `prepare` script. This script is executed as a hook by `npm` when you install all dependencies of the project (e.g. when running `npm install` for the first time), and we use it to install and initialize **Husky** at the project's root. You should not run this script manually. + +The other two scripts are `start` and `gbs`. The `gbs` script gives special access to the underlying `gobstones-script` CLI application, even if you didn't install it globally. You can run the `gbs` task run executing + +```sh +npm run gbs +``` + +This is equivalent to run the global `gobstones-scripts` command, as long as the local version and global version are the same. You may call `gobstones-scripts` sub-commands, such as `eject` or `update` by simply appending the command at the end. e.g.: + +```sh +npm run gbs update -i github +``` + +The `start` command is equivalent to running the `npm run gbs run` command, that is, it runs a task through `gobstones-scripts`, through the declared `nps` configuration. But `start` has the benefit of being a special task for node, so you can execute this command without having to do `npm run ` like for other scripts, you can simply do + +```sh +npm start +``` + +This will run the default script on the `nps` configuration, which most of the time will be abstracted away through `gobstones-scripts`. By default it prints a list of all the available tasks. + +The usual list of tasksthat we provide in any project are: + +* **help**: Shows a list of all possible commands that can be executed in the project. +* **dev**: Execute the current project in development mode. In libraries and CLI libraries, this implies executing the code in `src/index.ts`, in React libraries corresponds to running StoryBook in watch mode, and in applications it corresponds to executing the application in development mode. +* **build**: It generates a distributable file, usually in the `dist` folder. These are the files that other applications will use when importing the library, or that will be hosting by a server to use the application. +* **test**: Run all tests in the project. +* **doc**: Generate the project's documentation, usually at a folder named `docs`. +* **doc.serve**: Generate the project's documentation, and then serve the generated folder in a local server. +* **lint**: Run the linting process in all files, reporting styling and convention errors. +* **lint.fix**: Run the linting process in all files with the auto-fix feature as to correct automatically correctable errors. +* **prettify**: Fix the styling of all files in the project that can be solved automatically. + +Additional tasks may be present depending on the project itself. You can execute any task by simply running the `npm start` command followed by the task name. + +```sh +npm start +``` diff --git a/src/pages/coding/submission-workflow/index.md b/src/pages/coding/submission-workflow/index.md new file mode 100644 index 0000000..c014004 --- /dev/null +++ b/src/pages/coding/submission-workflow/index.md @@ -0,0 +1,219 @@ +--- +title: Submission Workflow +eleventyNavigation: + key: Submission Workflow + parent: Coding + order: 4 +--- +# Submission Workflow + +In order to submit code, you should be aware of the process to be assigned with tasks, generate code and submit it for addition into the main code base. This is a simple process, yet it's important to follow it in order to avoid multiple people working in the same task, or generate work that is not going to be considered for addition, as well as to keep a proper communication between the developers that contribute to the projects. + +--------------------------------------------------------------------- + +## Task assignment and management + +The project bases the organizational process through the use of **GitHub Issues** and **GitHub Projects** as explained in the [Service List Section](../../technologies/services-list/). + +How you get tasks assigned depends on whether you are an external contributor, or if you are an internal **Core Team** developer. Some things apply to either member of the development team, and you should be aware of them + +### The Gobstones Projects Boards + +In order to organize ourselves we make use of the **GitHub Projects** feature that allows us to display a board with all pending tasks to perform. No mather if you are part of the internal development team, or an external developer, you should check regularly the [Gobstones Organization Project's Page](https://github.com/orgs/gobstones/projects) in order to check what the pending tasks are. Select one of the projects and you will be presented with a tasks board. + +> Currently many projects are private, so only internal members of the team +> can see them. Once the project reaches a mature state, these project +> will be made public so anyone can easily contribute. + +In the board you will find 5 columns, named: + +* **Backlog**: Contains all the issues that comprise the product. This are not necessarily ready to start working on them, and some of them may even be simple desirable features, with no planned roadmap or consideration if they are actually doable, or which actual repository they will affect. You may expect to see a "Draft" status in many of them. +* **Pending**: Contains all the issues that have been assessed as doable, and desirable in the short term. This are issues nobody is working on yet, but that someone might claim to start work on. All of this tasks are already matched to an issue in a particular module and may even have people assigned to (even if they are not yet working on the task). +* **In Progress**: This are the tasks that developers are currently working on. Each task on this list will have someone assigned to, and will be mapped to an issue in a particular repository. +* **Requested for Revision**: This are the tasks that developers considered finished or require help with. When a developer finishes a task it will send a pull request to the main branch of the repository (more on this later). He can also do the same if it gets stuck with the task and requires help. It's expected that members of the **Core Team** check the code of this requests, and either approve the code, or help out the developer in need. +* **Done**: This are the tasks that have already been finished and approved. + +If you are panning on contributing you should focus on the **Pending** columns. Enter to the particular issue, see the description and discussion and either take the task (if you are an internal member of the team) or offer to do the task in the comments (if you are an external contributor). Once the task is assigned to you, you can move it to the **In Progress** column and start working on it. + +Once you are done and pushed code for the feature, it will be automatically moved to the **Requested for Revision**, and once approved, it should move automatically to the **Done** column. The process is explained in detail in the next sections. + +### Task creation + +Members of a project can create new tasks in the **Backlog** which will be assessed and moved to the **Pending** column by the team members or by the **Core Team**. External contributors cannot create tasks in this fashion. + +Once a task is created, some tags may be assigned to it, such as: + +* **Feature**: For tasks that involve adding new features. +* **Bug**: For tasks that involve correcting a bug. +* **Style**: For tasks that involve changing style or documentation. +Others may be used in the future and will be documented appropriately here if that is the case. + +In the case of external contributors, they cannot create tasks directly in the project, but they can report issues in any of the repositories the project is comprised of. Once an issue is reported, the members of the internal team will move the issue to an appropriate column, if it's an issue that should be regarded as important, or discard the issue completely (many issued reported are not actual feature request or bug reports, but request for help in the tool's usage or simple discussions about the tool). + +If you have a feature proposal and are en external contributor, be sure to create an issue in the corresponding (or the better matching) repository. + +--------------------------------------------------------------------- + +## Working with code + +Before embarking on any task, it's recommended that you have a working environment for the repository you are planning to work on. If you do not know how to configure an environment, please read the [Environment Setup Section](../../technologies/environment-setup) and be sure to clone the repository and test that everything is working. + +Once you have everything up and running and proved to work, you can follow the previous step to assign yourself a task. The you can start working on the feature or bug fix. + +### Working on a task (internal members of the team) + +The first step is to open the repository you cloned with you IDE, ideally VSCode, and open an embedded terminal. Run the `git branch` command to verify that you are in the main branch. You should see something like the following. + +```sh +$ git branch +* main +``` + +Other branches may be listed depending on the project, but you should ensure that you are on the `main` branch. + +Here, you should create and move to a new branch that will be used for the feature or bug fix you are working on. Use a relevant name that resembles the task name. You can do so by running + +```sh +git checkout -b add-some-feature +``` + +You can check you are in the created branch by running `git branch` again. + +At this point, you can write your code. Be sure to fulfill the expectations of the task, generate documentation for the code added or update it if something changed and that your code pass all the tests. + +Once everything is done, add all your files, commit and push to your branch. + +```sh +git add --all +git commit +git push origin add-some-feature +``` + +Go to **GitHub** and navigate to the repository of the module you are working on, you will be warned about changes in the new branch, and will be offered to generate a new pull request. Create one, and be sure that it points to `main` branch. + +> You may take your time to write your code, don't worry. +> You may even create partial commits, and upload the code to +> the branch before sending the pull request, nobody will touch +> that branch but you. +> +> Just be sure that your commits are clean before sending the +> pull request. + +Wait for other members of the project to review your code. If +improvements are requested address them by creating new commits and pushing to the same branch. Once the other members approve your code, it will be merged with the `main` branch. + +> It may happen that you are not finished with the feature you are working on, +> but you require help or review from other members of the team. In that +> case, just create a pull request in the same fashion you would to ask you +> merging, but be sure to let other members know that you are seeking help +> through the use of the pull request description. + +Now, switch to the `main` branch again in your local repository, by executing + +```sh +git checkout main +``` + +Fetch the latest changes from the `origin` remote by running: + +```sh +git pull origin main +``` + +You are now in `main` with the latest changes, including your newly approved task code already merged. You can repeat the process to address other tasks. But first, be sure to delete the branch you used for the previous issue, both from the local repository, as from the remote `origin`. + +```sh +git push origin :add-some-feature +git branch -D add-some-feature +``` + +> Be sure to always start new branches from `main`, and not from another +> feature branch. +> + +### Working on a task (external collaborators) + +If you are an external collaborator, the process for contributing is similar to the one for internal members of the team, but you will have to **fork** the repository, and work with two remotes instead. + +First, go to **GitHub** and seek for the repository you are going to work on. You will not have permissions on this repository, so you cannot add code to it. So what you need is to create a **fork** of the repository into your own user account. You will have all permissions in your fork, and you will be able to contribute code through it. + +Once the fork is done, open a terminal and clone the project from your user account. Do use SSH and not HTTPS. + +```sh +git clone git@github.com:/.git +``` + +Then, navigate to the project folder from your terminal and add the Gobstones organization repository as a new remote by the `upstream` name. + +```sh +git remote add upstream git@github.com:gobstones/.git +``` + +Now you should be able to execute the following command and see the output: + +```sh +$ git remote -v +origin git@github.com:/.git +upstream git@github.com:gobstones/.git +``` + +Now you should follow the same steps as an **internal team member**, with some slight differences. Please consider that, when generating a pull request, the target of the request should be the `main` branch of the original Gobstones organization repository, and not the one in your user account. That is, you should target `main` at `gobstones` not `main` at `your-username`. + +Also, once the feature is merged, you will want to update your repository with the latest changes in the `upstream`, and not the `origin`. Run the following commands. + +```sh +git checkout main +git pull upstream main +git push origin main +``` + +Now you should be in the main branch, and your `upstream` and `origin` should be synchronized with the latest changes. You are ready to repeat the process to take on new tasks. + +> If you happened to have the repository already in your machine because you +> worked on tasks on it a while ago, you should always sync with the upstream +> repository before starting a new feature, as new code might have been added +> to the `upstream`` but your`origin` will not reflect it. + +### Some considerations + +The are some final consideration to take into account when developing and before submitting code. + +* Be sure that the code can be built successfully by running + +```sh +npm start build +``` + +* Make sure that there are no linting errors and that all tests pass, with sufficient coverage by running + +```sh +npm start test +``` + +* Be sure that the generated documentation reports no errors or warnings about wrong links or unused properties by executing + +```sh +npm start doc +``` + +If everything is successful, then proceed on performing the pull request. Most of this check will also be automatically performed when attempting to push code, such as running the tests, and you will be blocked from pushing if the tests fail. + +Another thing to consider is that **Comitizen** will be triggered when attempting to generate a commit, providing you a wizard in the terminal that will guide you through the generation of a **conventional commit**. Be sure to add the information about what issue is being closed upon the code you are writing. + +Finally, please be sure to not left traces of dead code or debug code in your submission. + +--------------------------------------------------------------------- + +## Release process + +The release process is perform by a member of the **Core Team** with privileges to create tags in the repository. + +When a new tag with the format `v< semVer >` is created and published, a **GitHub Action** workflow will be triggered and the project will be published to both **npmjs** and **GitHub releases**. + +The release process will also trigger the generation of a the `CHANGELOG.md` file in your local machine, before pushing the new tag. So there is no need to updated the changelog manually. + +Publishing a new version of a library or component will not make the Gobstones application make use of it immediately. The application's dependencies should instead be updated to reflect the version change. Then, a new version of the application should be released and published in order for the changes to have effect under the actual productive application. + +This implies that, updating a library that everyone is dependant upon will spawn a version increase on many libraries, so the team should carefully plan the release process. This is one of the downsides of the **polyrepo** model. Yet, it's expected that, once libraries are mature enough, they will not likely change over and over, specially the core components. + +As a contributor you should be aware that you additions, once approved, will be incorporated soon enough to the productive environment. diff --git a/src/pages/coding-standards/testing/index.md b/src/pages/coding/testing/index.md similarity index 96% rename from src/pages/coding-standards/testing/index.md rename to src/pages/coding/testing/index.md index b253773..d6fc5d2 100644 --- a/src/pages/coding-standards/testing/index.md +++ b/src/pages/coding/testing/index.md @@ -2,7 +2,7 @@ title: Testing eleventyNavigation: key: Testing - parent: Coding Standards + parent: Coding order: 5 --- # Testing **GobstonesWeb2** projects @@ -11,28 +11,16 @@ One of the important aspects of the code you add to any project implies complyin This section explains how to run the tests, as well as how tests are organized and how to write new tests. ------------------------------------------------------ +--------------------------------------------------------------------- ## Running tests -Every project includes a `test` script in their `package.json` file. Running the tests is as easy as executing the script through `npm` by running: - -```sh -npm run test -``` - -The default test action consist in calling one of the defined `nps` commands with the name `test`, and `npm start` will run such commands, so the previous command it's simply a rename of the following: +Every project includes a `test` task in their `nps` configuration. Running the tests is as easy as executing the `gobstones-scripts run` command for the `test` task through `npm` by running: ```sh npm start test ``` -At the very end, `nps` is not even run directly but through `gobstones-scripts`, so if you have `gobstones-scripts` globally installed, the following command will also be equivalent: - -```sh -gobstones-scripts run test -``` - The actual tool running the tests is `jest`, which by default executes all the tests in the `./test` folder that have a name ending with the `.test.ts` extension. Each file is a **Test Suite** containing one or more **Tests**. In itself, each **Test** should consist in one or more **Assertions**. When running through the previous commands, all tests in all tests suites are executed. @@ -49,7 +37,7 @@ npm start test.serve Static files for the site are always saved in the `./coverage` folder when running the tests, and are deleted and recreated from scratch every time the tests are run. This folder is not preserved anywhere, and only serves the purpose of temporary serving for easier test result navigation. ------------------------------------------------------ +--------------------------------------------------------------------- ## Test Types in use @@ -67,8 +55,7 @@ Functional tests are written from the end user's perspective. If unit tests ensu Integration tests ensure that different modules are working together appropriately. In the more complex modules of the system, there is a need to ensure that different sub-modules are integrated in such a way that the whole expected behavior is met. In such cases, integration tests are used. - ------------------------------------------------------ +--------------------------------------------------------------------- ## Test Suite Organization @@ -90,19 +77,21 @@ We organize tests as files as follows: Tests suites code organize their contents (tests) in a particular way also. We got inspiration from the [Gherkin language](https://cucumber.io/docs/gherkin/reference/) and BDD, and we wrote our tests in such a way that they are human readable and can be used as part of the documentation of features and the expected interface. In that sense, we do not use Gherkin nor any domain specific language, but we do exploit **Jest**'s `describe` in order to write more meaningful test suites. We use the following three exported functions from `@jest/globals`: + * `it`: Used for defining a particular test case. We use it to describe what should happen when a particular method is called, sometimes with a particular input. * `expect`: Used to define assertions over a particular value or action. They are used inside tests as to to assert the state in which the system ends after executing some code. * `describe`: Used for grouping tests into a cohesive unit. We use it to describe the module or class under test. Defines a test group. * `beforeEach`: Used to setup a particular state in the system or objects under a test group before each test is run. But, we also make use of some aliases of `describe` that allows for more human readable and meaningful tests. + * `given`: Allows us to define a grouping of tests that require a particular initial state. It groups multiple tests, and usually contains a `beforeEach` definition, that sets the state in a particular fashion. It's an alias for `describe`. * `when`: Allows us to specify the method or function to test. It's an alias for `describe`. * `withInput`: Allows us to specify input data for the particular test or function. It's an alias for `describe`. Full tests should be read in such a way that combining all the describes, given, when, on and it, makes a coherent text that explains the feature or scenario under testing. -Here are some examples: +Here is an example: > **DESCRIBE** Stack > **GIVEN** an instance with multiple elements @@ -122,6 +111,8 @@ Here are some examples: > }); > ``` +And another one: + > **DESCRIBE** Stack > **GIVEN** an instance with multiple elements > **WHEN** push **WITH INPUT** "X" @@ -148,8 +139,8 @@ Here are some examples: > }); > }); - You can import all of them as follows: + ```ts import { it, expect, describe, @@ -170,7 +161,6 @@ The following are common guidelines that you should follow when writing test sui * Use present simple over present continuous. That is, prefer "returns 5" over "returning 5". * When doing unit testing, if your module or class is intertwined with others, be sure to use **mocks** to simplify testing and test a single module at a time. Only tet the full behavior if impossible to mock, or if the element under test cannot live without an instance of the other. - ### Test examples for particular scenarios Of course some of this test rules have their oun interpretation when testing different elements in the code. Let's see some particular common examples of tests: @@ -405,14 +395,14 @@ describe('reverse', () => { }); ``` -How to test react components - +How to test React components ### Unit test of modules with static objects Usually, when a module returns an object, that object contains no state that can or should be modified from the exterior. In such cases, we will test the object in a similar way as we test classes, except that there will be no `given` clause, as there are no states that are relevant for the object. An example of this would be something like: + ```ts describe('stringUtilities', () => { when('equalsIgnoringCase', () => { @@ -428,6 +418,7 @@ describe('stringUtilities', () => { In some particular scenarios, the state of the object may be important, and may be changed from outside. If that is the case, then you may use `given` clauses to specify a particular state for the object. Do note that, if the object is global, the object will not go back to it's original state after every test run. You should have this in mind when writing such tests, and use the `beforeEach` and `afterEach` or `beforeAll` and `afterAll` in each `given` context to set up the object in a well known state. An example of this particular case will look like the following: + ```ts describe('globalStack', () => { given('global stack has two elements', () => { @@ -446,7 +437,6 @@ describe('globalStack', () => { Functional tests are a little different than unit tests, as they assert the behavior of a full module, from the perspective of a user, and not the developer. In this tests we will not validate individual methods, but overall interface behavior, thus, ensuring that the overall module behaves as required in a realistic use case scenario. - ```ts describe('Stack', () => { given('a newly created stack', () => { diff --git a/src/pages/coding/writing-documentation/index.md b/src/pages/coding/writing-documentation/index.md new file mode 100644 index 0000000..a5eb094 --- /dev/null +++ b/src/pages/coding/writing-documentation/index.md @@ -0,0 +1,54 @@ +--- +title: Writing Documentation +eleventyNavigation: + key: Writing Documentation + parent: Coding + order: 6 +--- +# Writing Documentation + +An important aspect about any code is it's documentation. We know that writing test cases and documentation usually takes even more time than writing the code itself, but we aim to produce a premium quality software. In that sense, we encourage all of our developers to produce documentation that is accurate, understandable and up to date. + +> Previous versions of **GobstonesWeb** had poor to none documentation +> nor testing, and mainlining it was a real problem, specially in a project +> where collaborators are changing all the time. + +We make use of [**TypeDoc**](https://typedoc.org) for generating the documentation. You should get familiar with the technology before starting to write code for the project. If you have used other documentation tools in the past, like JavaDocs or JSDocs, you will find the syntax quite familiar. + +--------------------------------------------------------------------- + +## Documentation considerations + +There is not much to say about how to write good documentation, other than that it should be clear, succinct and be up to date with the code. But please do consider the following. + +* When documenting functions or methods, be sure to add a `@param` tag for each parameter and document it appropriately. This goes for both public and private methods. +* Use the `@return` tag to clarify the expected return value. +* Ue the `@throws` tag to declare situations in which the function or method may fail, and link to the appropriate error type if necessary. +* Be sure to add the `@internal` tag to all elements that are public, but are module internal (e.g. module level elements or package level visibility). +* Do use the `@group` tag to set an appropriate group fro the elements. We use the following conventions: + * `API` group is for elements that the module exports and that others are expected to use from outside the module. Use sub-grouping to differentiate by element type or functionality, such as **API: Types**, **API: Functions**, **API: Accessors**, etc. + * `Internal` group is for elements that are internal to the module and should not be used from outside. Use sub-grouping to differentiate by element type or functionality, such as **Internal: Helpers**, **Internal: Types**, etc. +* Use the header of the document to declare the file author and the module it belongs by using the `@author` and the `@module` tags. +* Document modules/sub-modules in their corresponding `index.ts` file only, as the per the barrel pattern, all files in the module should belong to the same module. +* Use appropriate module names following the same convention than the one used for elements: `API` for modules that may be used externally (e.g. are exported to the full module user) and `Internal` for modules that are not going to be exported. +* Use the `@link` tag when mentioning other classes or attributes a to generate a pleasant navigation experience to the reader of the docs. + +Bear this in mind and you will end up writing great documentation. + +## Building and checking the documentation + +All our projects (except the guidelines itself) have an `nps` task to generate the documentation. You can run it by executing + +```sh +npm start doc +``` + +Ensure that there are no warnings or errors when building. Once you are sure everything is building Ok, you may still verify manually that everything looks as expected by navigating the documentation locally. Run the tak to generate the documentation and start a local server with the output. + +```sh +npm start doc.serve +``` + +You should see the documentation at your `localhost:3000` port. + +Remember that the documentation is not uploaded to the sources of the project and that it will be automatically generated when a new version of the project is released (a new tag is created). diff --git a/src/pages/governance/communication/index.md b/src/pages/governance/communication/index.md new file mode 100644 index 0000000..4ba5625 --- /dev/null +++ b/src/pages/governance/communication/index.md @@ -0,0 +1,36 @@ +--- +title: Communication +eleventyNavigation: + key: Communication + parent: Governance + order: 2 +--- +# Communication + +Depending on the needs and on what do you want to communicate, we have different contact channels. + +--------------------------------------------------------------------- + +## Gobstones Community Server + +If you want to join other users to exchange comments, information and experiences, you should join the [**Gobstones Community**](http://bit.ly/ComunidadGobstones) server at [Discord](https://discord.com). + +Be sure to [Create a Discord Account](https://discord.com/register) if you don't have one already, link it to your cell phone and protect it, and then join the server. + +This is **the** place to be if you are into **Gobstones**. Also, if you want to talk directly to the development team, you may join the community server, as the team usually hangs there. + +The language spoken in the server is mostly spanish, yet all nationalities and languages are welcome. + +--------------------------------------------------------------------- + +## GitHub's Organization Page + +If you want to report bugs or issues, you should go to the [GitHub's Organization Page](https://github.com/gobstones). + +You should report them in the appropriate repository, so it would be nice if you are aware of the [Project's Architecture](../../architecture) in order to do that. + +Issues at GitHub is the main way in which we communicate about the project's development and problems with the software. If you are looking to contribute with code, you should start there. + +## Core + +The Core Team holds meetings virtually every thursday through Discord itself. diff --git a/src/pages/governance/contact/index.md b/src/pages/governance/contact/index.md deleted file mode 100644 index 70f8a4a..0000000 --- a/src/pages/governance/contact/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Contact -eleventyNavigation: - key: Contact - parent: Governance - order: 2 ---- -# Contact us and the community - -Depending on the needs and on what do you want to communicate, we have different contact places. - -If you want to join other users to exchange comments, information and experiences, you should join the [**Gobstones Community**](http://bit.ly/ComunidadGobstones) server at Discord. The language spoken in the server is mostly spanish, yet all nationalities and languages are welcome. - -Also, if you want to talk directly to the development team, you may join the community server, as the team usually hangs there. - -If you want to report bugs or issues, you can report them at our [GitHub's organization page](https://github.com/gobstones). You should report them in the appropriate repository, so it would be nice if you are aware of the [project's architecture](../../architecture) in order to do that. diff --git a/src/pages/governance/core-team/index.md b/src/pages/governance/core-team/index.md deleted file mode 100644 index 528332a..0000000 --- a/src/pages/governance/core-team/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Core Team -permalink: /governance/core-team/ -eleventyNavigation: - key: Core Team - parent: Governance - order: 1 ---- -# Current **Core Team** - -The list of current members of the **Core Team** deciding all the major aspects of the **Gobstones Project** including the development of **GobstonesWeb2** are: - -**Project founder and product owner** - * Pablo E. --Fidel-- Martínez López, [github.com/fidel-ml](https://github.com/fidel-ml) - -**Team leader and lead developer** - * Alan Rodas Bonjour, [github.com/alanrodas](https://github.com/alanrodas) - -**Developers** -* Juan Cruz Insaurralde, [github.com/Juan-Insa](https://github.com/Juan-Insa) - ---------------------------------------------------------------------- - -There is also a list of close advisors, that sometimes are also involved in making decisions. They are: - -**Project advisors** - * Gonzalo Pablo --Perla-- Fernández Florio, [github.com/gpfernandezflorio](https://github.com/gpfernandezflorio) - * Leonardo Marina, [github.com/leomarinag](https://github.com/leomarinag) - * Federico A. Sawady O'Connor, [github.com/sawady](https://github.com/sawady) - * Federico Aloi, [github.com/faloi](https://github.com/faloi) - * Pablo Barenbaum, [github.com/foones](https://github.com/foones) - ---------------------------------------------------------------------- - -The **Gobstones** project was born at the National University of Quilmes, at Argentina, and has now expanded to other universities in Argentina, high schools and even international institutions. Researchers, developers, and users, mostly from (but not limited to) those institution conform the **Gobstones Community**. All people interested in **Gobstones** conform the community, and provide comments and feedback that help us improve the project and they are deemed as project stakeholders. You can see how to join the community at the [contact section](../contact) diff --git a/src/pages/governance/decision-making/index.md b/src/pages/governance/decision-making/index.md index c54c008..bbd853e 100644 --- a/src/pages/governance/decision-making/index.md +++ b/src/pages/governance/decision-making/index.md @@ -3,14 +3,94 @@ title: Decision Making eleventyNavigation: key: Decision Making parent: Governance - order: 2 + order: 1 --- # Decision Making -Currently, the project decision making is handled by a [**Core Team**](../core-team) of researchers and developers that currently take all major decisions regarding the language and the environments, thus providing direction, defining the metrics for validating impacts to the project, and providing the tools needed to communicate, deliver on requirements, etc. +Currently, the project decision making is handled by the **Core Team**. These team currently takes all major decisions regarding the language and the environments, thus providing direction, defining the metrics for validating impact to the project, and providing the tools needed to communicate, deliver on requirements, etc. -**GobstonesWeb2** is an open source project aimed at providing a new version of the current environment, with a solid architecture that is understandable, maintainable, and extensible. The **Core Team** is actively engaged in completing a MVP, and holds regular meetings regarding the development of the project every thursday. These meeting are currently not open to the community, but we might held open meetings in the future. +## Current **Core Team** -We expect to be able to have a formal committee at some point that meets regularly in the future and to be able to have open meetings where all the community could join. +The list of current members of the **Core Team** deciding all the major aspects of the **Gobstones Project** including the development of **GobstonesWeb2** are: -All community members are welcome to report issues at our [GitHub's organization page](https://github.com/gobstones), and the **Core team** will assess them and determine a priority for the issue. + +
+ Pablo E. --Fidel-- Martínez López's avatar +
+

Pablo E. --Fidel-- Martínez López

+

Project founder and product owner

+

+ Full Professor at University of Quilmes, in Argentina. 30 years + dedicated to the great profession of teaching young generations + of Computer Scientists et al. +

+ See GitHub profile +
+
+ +
+ Alan Rodas Bonjour's avatar +
+

Alan Rodas Bonjour

+

Team leader and lead developer

+

+ Full Stack developer. Professor at National University of Quilmes, in Argentina. +

+ See GitHub profile +
+
+ +
+ Juan Cruz Insaurralde's avatar +
+

Juan Cruz Insaurralde

+

Developer

+

+ Full Stack developer. Professor at National University of Quilmes, in Argentina. +

+ See GitHub profile +
+
+ + +The **Core Team** is actively engaged in completing an MVP, and holds regular meetings regarding the development of the project every thursday. These meeting are currently not open to the community, but we might held open meetings in the future. + +--------------------------------------------------------------------- + +## Project advisors + +**GobstonesWeb2** is an open source project aimed at providing a new version of the current environment, with a solid architecture that is understandable, maintainable, and extensible. + +In the search for implementing the bet possible policies there is also a list of close advisors on whom we trust, that sometimes are also involved in making decisions. They are: + +* Gonzalo Pablo --Perla-- Fernández Florio, [github.com/gpfernandezflorio](https://github.com/gpfernandezflorio) +* Leonardo Marina, [github.com/leomarinag](https://github.com/leomarinag) +* Federico A. Sawady O'Connor, [github.com/sawady](https://github.com/sawady) +* Federico Aloi, [github.com/faloi](https://github.com/faloi) +* Pablo Barenbaum, [github.com/foones](https://github.com/foones) + +--------------------------------------------------------------------- + +## Project community + +The **Gobstones** project was born at the National University of Quilmes, at Argentina, and has now expanded to other universities in the country, high-schools and even international institutions. Researchers, developers, and students, from all those institution conform what we call the **Gobstones Community**. + +We constantly seek comments and feedback from the community in order to improve, and we consider the members of the community as the major stakeholder of the project. + +The community is not exclusive, anyone interested in **Gobstones** can join the community, and participate. You can see how to join the community at the [Communication Section](../communication) + +--------------------------------------------------------------------- + +## Future plans + +Currently the project is open, but we remain a little closed. In the future we expect to be able to have open meetings with the project roadmap on discussion, where all the community can join to hare their ideas and vision, and make a more rich exchange. + +Also, we would like to have a formal committee that meets regularly to take the decision, and let the decision making not be only part of the core team's decisions. + +We are still learning and working hard to improve the **Gobstones Open Source Community**. Please share any comments as to how we can improve, they will be greatly appreciated. diff --git a/src/pages/governance/index.md b/src/pages/governance/index.md index 51d88ba..6e592ed 100644 --- a/src/pages/governance/index.md +++ b/src/pages/governance/index.md @@ -5,31 +5,27 @@ eleventyNavigation: parent: Overview order: 2 --- -# Governance and flow of communication +# Governance Welcome to the first step in contributing the Gobstones organization. The first thing you need to know in order to collaborate is how and by who the project is governed, and the second is how to keep in touch with the latest news and to get in touch with the core team. --------------------------------------------------------------------- -## Core Team - -There is a lot of people working in and with **Gobstones**. There are researchers, developers, teachers and students from different places of the world, that contribute in different ways. The development of the project and decision making is managed by a **Core Team** deciding all the major aspects of the **Gobstones Project** including the development of **GobstonesWeb2** are: - -You can see the members of the current **Core Team** at the [Core Team](./core-team) section. - ---------------------------------------------------------------------- - ## Decision Making +There is a lot of people working in and with **Gobstones**. There are researchers, developers, teachers and students from different places of the world, that contribute in different ways. + Project governance provides direction and defines decision making in all aspects of the **Gobstones Project**, including the language itself, the didactics, and the development environments. -You can read about how the process of decision making works at the [Decision Making](./decision-making) section. +These decisions and the main development of the project is managed by a **Core Team** deciding all the major aspects of the **Gobstones Project** including the development of **GobstonesWeb2**. + +You can read more about the decision making project and get to know the members of the current **Core Team** at the [Decision Making Section](./decision-making). --------------------------------------------------------------------- -## Flow of communication +## Communication Flow of communication guarantees that all contributors are aware of the latest decisions in the project that may affect them. Depending on the needs and on what do you want to communicate, we have different contact channels. -You can read more about how to communicate with the team depending in your needs at the [Contact](./contact) section. +You can read more about how to communicate with the team depending in your needs at the [Communication Section](./communication). diff --git a/src/pages/index.md b/src/pages/index.md index 55aa3b3..8ddd8af 100644 --- a/src/pages/index.md +++ b/src/pages/index.md @@ -4,27 +4,27 @@ eleventyNavigation: key: Overview order: 1 --- -# Guidelines to contribute to **GobstonesWeb2** development +# Overview This repository contains documentation on the platform architecture, design guidelines, ways to contribute, and standards used, related to the development of **GobstonesWeb2**. [![License](https://img.shields.io/github/license/gobstones/gobstones-guidelines?style=plastic&label=License&logo=open-source-initiative&logoColor=white&color=olivegreen)](https://github.com/gobstones/gobstones-guidelines/blob/main/LICENSE) [![Version](https://img.shields.io/github/package-json/v/gobstones/gobstones-guidelines?style=plastic&label=Version&logo=git-lfs&logoColor=white&color=crimson)](https://github.com/gobstones/gobstones-guidelines) -If you are planning on contributing to the development of **GobstonesWeb2** in any way, please start by reading the guidelines. - -**Find the [guidelines start page here](./introduction)** - --------------------------------------------------------------------- -Be sure to: +If you are planning on contributing to the development of **GobstonesWeb2** in any way, you need to be sure to: + * Understand how **GobstonesWeb2** architecture is organized in different repositories. * Be aware of the relationships of all the different repositories. * Learn about the technologies being used in common through all projects. * Get to know the project governance chain and communication channels. * Maintain the code standards for all projects and code submissions. ---------------------------------------------------------------------- +To do so, please start by fully reading the guidelines. + +**Find the [guidelines start page here](./introduction)** -If you want to know more about this repository itself, you may read the [about the guidelines](./about-guidelines) section in the guidelines. +--------------------------------------------------------------------- +If you want to know more about this repository itself, you may read the section titled ["About guidelines"](./about-guidelines) diff --git a/src/pages/introduction/index.md b/src/pages/introduction/index.md index 8d89511..4c8bb42 100644 --- a/src/pages/introduction/index.md +++ b/src/pages/introduction/index.md @@ -7,42 +7,40 @@ eleventyNavigation: --- # Introduction to the **GobstonesWeb2** guidelines -The gobstones-guidelines contain documentation on the platform architecture, design guidelines, ways to contribute, and standards used, related to the development of **GobstonesWeb2**. +The Gobstones-guidelines contain documentation on the platform architecture, design guidelines, ways to contribute, and standards used, related to the development of **GobstonesWeb2**. -There are 4 main sections on the guidelines. Depending on the way you are planning to contribute, you may need to know only some of them, or you may need to know them all. +There are 4 main sections on the guidelines. Depending on the way you are planning to contribute, you may need to get acquainted only some of them, or you may need to deeply know them all. The sections are the following: --------------------------------------------------------------------- -## Governance and flow of communication +## Governance -Project governance provides direction and defines decision making. -Flow of communication guarantees that all contributors are aware of the latest decisions in the project that may affect them. +To contribute to any project you should know how the project is managed, who are the members involved and their roles, and how the team and contributors communicate between each other -If you want to contribute in any way, even if it's not coding, you should be aware of everything in this section. So be sure to read the [governance](../governance) section so you can learn how do we work, who are we and how to get in touch with us. +If you want to contribute in any way, even if it's not coding, you should be aware of everything in this section. So be sure to read the [Governance Section](../governance) so you can learn how do we work, who are we and how to get in touch with us. --------------------------------------------------------------------- -## Architecture of **GobstonesWeb2** +## Architecture The architecture of **GobstonesWeb2** combines several modules providing different functionalities, each module in it's own repository, and with different technologies. -If you are planning on getting deeper into how **GobstonesWeb2** works, and which are the major parts of the system, you should read the [architecture](../architecture) section to know more about all the modules and how they interrelate. +If you are planning on getting deeper into how **GobstonesWeb2** works, and which are the major parts of the system, you should read the [Architecture Section](../architecture) to know more about all the modules and how they interrelate. --------------------------------------------------------------------- -## Technologies used +## Technologies **GobstonesWeb2** is developed in `Typescript` and we use `Node.js` to develop, along several other technologies associated with those. -If you want to contribute with code in any way, or are planning on downloading and running any of the modules on your own, you should read the [technologies](../technologies) section to learn about the technologies we use and how to use them. +If you want to contribute with code in any way, or are planning on downloading and running any of the modules on your own, you should read the [Technologies Section](../technologies) to learn about the technologies we use and how to use them. --------------------------------------------------------------------- -## Coding standards and workflow +## Coding -We follow a series of standards when coding and naming elements, and also a specific workflow. -Please, be sure to follow those standards when contributing to the project. +We organize our projects in a particular way, we follow a series of standards when coding and naming elements, document the code or write tests, and we expect participation of contributors in a particular way that you should be aware of. -If you want to contribute with code in any way, please note that we do not accept code that does not follow this standards. So be sure to read the [coding standards](../coding-standards) section to learn about how do we code. +If you want to contribute with code in any way, please note that we do not accept code that does not follow the standards and workflows explained in this section. So be sure to read the [Coding Section](../coding) to learn about how do we code. diff --git a/src/pages/technologies/environment-setup/index.md b/src/pages/technologies/environment-setup/index.md new file mode 100644 index 0000000..3dbd262 --- /dev/null +++ b/src/pages/technologies/environment-setup/index.md @@ -0,0 +1,259 @@ +--- +title: Environment Setup +eleventyNavigation: + key: Environment Setup + parent: Technologies + order: 3 +--- +# Environment Setup + +Setting up a working environment for coding is not always easy, so this section is intended to guide you through such setup. We provide guides for different operating systems, and then some additional steps that are common to all systems. + +--------------------------------------------------------------------- + +## Installation guide for different operating systems + +### Linux based systems + +To install on a Linux system you should probably delegate into your system's package manager, such as `apt`, `dnf` or `pacman`. + +You need to install **Git**, **Node.js** and **npm** (which usually comes bundled with Node.js, but in some systems comes as a separate package) through your package manager. You can find instructions for many different distributions in the **[official Node.JS installation instructions](https://nodejs.org/en/download/package-manager)**. + +In Ubuntu and derivatives you can run: + +```sh +sudp apt update +sudo apt install git Node.js npm +``` + +Depending on the version, you may need to download a **snap** version of it. + +On Fedora, RHEL or CentOS you can: + +```sh +dnf module install nodejs: +``` + +where _< stream >_ corresponds to the major version of Node.js. To see a list of available streams you can run `dnf module list nodejs`. Always choose the latest version. + +### macOS + +On macOS the recommended way to install is through [Homebrew](https://brew.sh). +If you don't have Homebrew already installed, follow the setup process explained on their website. The just launch a Terminal and run: + +```sh +brew install git node +``` + +This will install **Git**, **Node.js** and **npm**, which you will be able to use from any terminal. Be sure that you are using the latest version of **Git** as per the one installed with Homebrew, and not the **macOS built-in Git version**. + +### Windows for non WSL users + +You can install the required software through their corresponding website. But for **Git** installation, you should carefully select the components to install in the installation wizard, so we will describe each step of the installation process. + +#### Installing Git + +* Download Git from the [Official Git Website](https://git-scm.com/download/win) and start the installation wizard. +* Select Destination Location + * The first tep of the wizard will ask you for the destination location in which you wish to install Git. Select the one you like, or leave the default one, `C:\Program Files\Git`. +* Select Components + * In the component selection, be sure to check "Add a Git Bash Profile to Windows Terminal" option. You should leave the rest as default. +* Select Start Menu Folder + * As the menu folder name, you may choose whatever you please, but you may leave the default `Git` option. +* Choosing the default editor used by Git. + * When choosing the editor for commit messages, we recommend to use the `Vim editor`, which runs on the terminal. If you want a visual editor, you may choose `Visual Studio Code`, but be sure to install it beforehand. +* Adjusting the name of the initial branch in new repositories. + * When choosing the default branch name, be sure to select "main" as the default. +* Adjust your PATH environment + * Select the option "Use Git and optional Unix tools from the Command Prompt". +* Choosing the SSH executable + * Select the option "Use bundled OpenSSH". +* Choosing HTTPS transport backend + * Select the option "Use the OpenSSL library". +* Configuring the line ending conversions + * Select "Checkout as-is, commit Unix-style line endings" +* Configuring the terminal emulator to use with Git Bash. + * Select "Use Windows default console window" as the terminal emulator to use with Git Bash. +* Choose the default behavior on `git pull` + * Select "Only ever fast-forward" as the default behavior for `git pull`. +* Choose a credential helper + * Select "Git Credential Manager". +* Configuring extra options + * Select both the "Enable file-system caching" and the "Enable symbolic links" options. +* Configuring experimental options + * Do not select any of the options. + +Hit install and wait for the operation to finish. When prompted, you can skip the option to view the readme file and click the Finish button. + +You should now be able to use `git`. + +#### Installing Node.js + +* Download Node.js from the [Official Node.js page](https://nodejs.org/en). Select the latest version, not the LTS version. Then run the installation wizard. +* Accept the agreement and continue to select the installation folder, you may choose any folder you like, but we recommend to stick with the default `C:\Program Files\nodejs`. +* When prompted for Custom Setup, leave everything as default. +* Tools for Native Module + * On the window to install native tools, be sure to select the "Automatically install the necessary tools" option. And hit install. + +This will not only install Node.js but also additional tools, including the `chocolatey` package manager, a `C/C++ compiler` and `python`. This will be installed later in a terminal window. When prompted in the terminal window, be sure to press the ENTER key every time. If the "Do you want to allow changes in the system" prompt appears, choose "Yes". + +### Set the execution policy level + +You will be using Windows PowerShell to execute scripts and others. In order to be able to execute everything you will need to set up your execution policy level as to bypass the signature requirements. + +Open a PowerShell terminal and execute: + +```sh +Set-ExecutionPolicy Bypass -Scope LocalMachine +Set-ExecutionPolicy Bypass -Scope CurrentUser +``` + +### Windows for WSL users + +If you are using **Windows Subsystem for Linux (WSL)**, you should install in the same way as a Linux user using the WSL terminal. + +We recommend to install the **Ubuntu** version for WSL, as it's proven to work. + +--------------------------------------------------------------------- + +## Common steps + +This steps should be followed in any system. You should be able to execute the presented commands from the shell, Terminal or PowerShell (according CLI depending on your system). In case any of them cannot run, you should re-install the corresponding tool, or verify your `PATH` variable to check that the installation has included the binaries into the `PATH`. + +### Verify installation and setup + +* Verify that `git` is installed: + +```sh +git --version +``` + +* Verify that `node` is installed: + +```sh +node --version +``` + +* Verify that `npm` is installed: + +```sh +npm --version +``` + +Then, configure the global information for Git: + +```sh +git config --global user.name "John Doe" +git config --global user.email "john-doe@company.com" +``` + +Then you can install the rest of the environment. + +### Install Visual Studio Code + +Visual Studio Code (VSCode for short) is a text editor that can be extended to transform it into a full fledge IDE. Although you may use any IDE that you want, most of us make use of VSCode, and most project's include configurations for setting up the VSCode environment automatically when you open the folder. + +Some systems include VSCode in their software store (You can find it in the Windows Store if you are using Windows, in some Software applications on Linux, and the App Store on macOS). The easiest way however is to download the binaries from the [Official Visual Studio Code Download Page](https://code.visualstudio.com/download) which provides binaries for most of the operating systems and architectures. + +Follow the installation wizard with default setup if prompted. + +### Install n + +`n` is a tool that allows to manage the version of `Node.js` installed, and switch to different versions, update and others. `n` is installed through `npm`. Install it globally by running: + +```sh +npm install --global n +``` + +After that, you should be able to execute the `n` command in your terminal. + +### Be sure to always use latest versions of Node.js and npm + +You should be sure to run the latest versions of `npm` and `Node.js`. This can be executed every now and then, and usually `npm` will warn you when there is a new version of the tool to install. + +Run the following to update `node`: + +```sh +n latest +``` + +You should now have the latest version of node that you can verify through `node --version`. + +You may also need to update `npm`, which you can do: + +```sh +npm update --global npm +``` + +### Installing Gobstones-scripts globally + +If you need to create new projects from scratch, you may want to delegate the process into `gobstones-scripts`. For that, you may need to install the tool globally. You can do it by running the following command: + +```sh +npm install --global @gobstones/gobstones-scripts +``` + +Note that you may not require this if you are not needed to create new projects. + +--------------------------------------------------------------------- + +## Downloading existing projects + +To download and execute existing projects from **GobstonesWeb2** you should clone the repository from **GitHub**. Go to [Gobstones organization at GitHub's](https://github.com/gobstones) and choose the repository you want to download. + +Then clone it using your terminal. Navigate to the location you want to download the project and execute: + +```sh +git clone git@github.com:gobstones/.git +``` + +Replacing _< project-name >_ with the corresponding project name. + +> If you are using WSL you should open a WSL terminal, not a simple +> PowerShell terminal. If you are using Windows without WSL you can +> open a PowerShell terminal. +> +> In WSL the folder where the project is downloaded is mapped to a +> older in your file system. Be sure to register which folder it is, +> as you may need it later. + +Then move to the project folder in your terminal and download the dependencies by running: + +```sh +npm install +``` + +You can now start running the project, but you may want to open it with **Visual Studio Code**. Open VSCode and then select the option to **Open folder**. Select the folder in which you have downloaded the project and open it. + +> If this is the first time opening a **GobstonesWeb2** project in VSCode, you may be prompted to install several add-ons on your editor. Do install them all. + +When working on VSCode it's way easier to use the integrated terminal console to work with your project. We recommend you select the option "Terminal -> New Terminal" or "Console -> New Console" from the menu, to use the bottom drawer as a terminal. + +> If using WSL you should use the `><` icon on the lower left corner +> of the window, and select `New WSL Window`. The icon on the lower +> left corner should change to `>< WSL: `. + +--------------------------------------------------------------------- + +## Testing that projects are working correctly + +You may check that all commands run properly on the new project. On the VSCode terminal, execute the following commands and verify that everything produces a satisfactory output. + +```sh +npm start dev +npm start build +npm start test +npm start doc +``` + +If something is not working, be sure to contact us by [Creating a new issue on the Gobstones-guidelines project](https://github.com/gobstones/gobstones-guidelines/issues) so we can improve this guide. + +--------------------------------------------------------------------- + +## Toggle debug mode + +You may require to debug your code. This can be easily achieved in VSCode by setting breakpoints, which can be done by clicking on the gutter of any file. + +Then, just toggle the _"Debug: Toggle Auto Attach" option, which you can do by accessing the **Command Palette** (Ctrl+Shift+P or Cmd+Shift+P) and selecting the option. You can run it again to disable the auto connect feature. + +If you select the "Always" option, then you will need to reload your built-in terminal (this will be marked by a yellow warning sign in your terminal icon). After that, any command you execute through npm will be ready to be debugged. diff --git a/src/pages/technologies/index.md b/src/pages/technologies/index.md index 8ca19dc..a2e271a 100644 --- a/src/pages/technologies/index.md +++ b/src/pages/technologies/index.md @@ -7,26 +7,29 @@ eleventyNavigation: --- # Technologies used in **GobstonesWeb2** -We make use of many different technologies and use several platform in order to develop **GobstonesWeb2**. If you're planning on contributing to the platform with code, or want to understand better how the different projects work, you should definitely read all the sections below. +We make use of many different technologies and use several platforms in order to develop **GobstonesWeb2**. If you're planning on contributing to the platform with code, or you want to understand better how the different projects work, you should definitely read all the sections below. --------------------------------------------------------------------- -## List of main technologies we use +## Technologies we use + +First you will need to get a grasp of all the different technologies we are using in the development of our modules. Being aware of all the technologies we use will allow you to understand what every configuration file in the project does, and why is it there. Some technologies, like `TypeScript`, that we use as the main programming language, are mandatory for you to learn, while for others is just enough for you to be aware of their existence, as it's not likely that you will have to directly use them or modify the default configurations. -First you will need to get a grasp of all the different technologies we are using in the development of our modules. Being aware of all the technologies we use will allow you to understand what every configuration file in the project does, and why is it there. ome technologies, like `TypeScript`, that we use as the main programming language, are mandatory for you to learn, while others are just enough to know they are there, as it's not likely that you will have to directly use them or modify the default configurations. Be sure to read the technology list before starting the contribution in any project by reading the [List of Technologies](./technology-list). --------------------------------------------------------------------- -## List of main services we use +## Services we use -Developing a full open source project like **Gobstones** requires not only technologies, but also services that allows the team to be in touch, share the code, perform code reviews, manage issues, publish artifacts and more. +Developing a full open source project like **GobstonesWeb2** requires not only technologies, but also services that allow the team to be in touch, share the code, perform code reviews, manage issues, publish artifacts and more. We make heavy use of third party services in order to achieve that, mainly through the **GitHub** ecosystem. + You may read a detailed list of all the services we use and how in the [List of Services](./services-list). --------------------------------------------------------------------- -## Installation tutorial for starting developers +## Environment setup for newcomers + +If it's your first time developing web applications in a `Node.js` platform, using `Git`, or have any doubts on how to get started, we are here to offer some help setting up your environment and getting you started. -If it's your first time developing web applications in `Node.js` platform, you may need some help setting up your environment. -We have developed an [Installation Tutorial](./installation-tutorial) for you to follow and be all setted up to start coding in any **GobstonesWeb2** repository. +We have developed an [Environment Setup](./environment-setup) for you to follow and have everything up and running to start coding in any **GobstonesWeb2** repository. diff --git a/src/pages/technologies/installation-tutorial/index.md b/src/pages/technologies/installation-tutorial/index.md deleted file mode 100644 index 3da707b..0000000 --- a/src/pages/technologies/installation-tutorial/index.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Installation Tutorial -eleventyNavigation: - key: Installation Tutorial - parent: Technologies - order: 1 ---- -# Instructions to install a repository, for newcomers - -## Windows for non WSL users - -You can install the required software through their corresponding website. -* [Download Visual Studio Code]() - * You may also opt for downloading through the **Microsoft Store**. -* [Download git](https://git-scm.com/download/win) - * Select Destination Location - * You may select any folder to install Git on. By default is usually `C:\Program Files\Git`, which is more than good. - * Select Components - * Be sure to check the "Add a Git Bash Profile to Windows Terminal" option. Leave rest as default. - * Select Start Menu Folder - * You may choose any Start Menu name for the folder, but the default `Git` will suffice. - * Choosing the default editor used by Git. - * When choosing the editor for commit messages, we recommend to use the Vim editor, or at most, Visual Studio Code, but you may choose your preferred one. - * Adjusting the name of the initial branch in new repositories. - * When choosing the default branch name, be sure to select "main" as the default. - * Adjust your PATH environment - * Select the option to "Use Git and optional Unix tools from the Command Prompt". - * Choosing the SSH executable - * Select "Use bundled OpenSSH". - * Choosing HTTPS transport backend - * Select "Use the OpenSSL library". - * Configuring the line ending conversions - * Select "Checkout as-is, commit Unix-style line endings" - * Configuring the terminal emulator to use with Git Bash. - * Select "Use Windows default console window" as the terminal emulator to use with Git Bash. - * Choose the default behavior on `git pull` - * Select "Only ever fast-forward" as the default behavior for `git pull`. - * Choose a credential helper - * Select "Git Credential Manager". - * Configuring extra options - * Select both the "Enable file-system caching" and the "Enable symbolic links" options. - * Configuring experimental options - * Do not select any of the options. - Hit install and wait for the operation to finish. When prompted, you can skip the option to view the readme file and click the Finish button. - -* [Download Node.js](https://nodejs.org/en) - * Select the latest LTS build. - - * Accept the agreement and continue to select the installation folder, you may choose any folder you like, but we recommend to stick with the default `C:\Program Files\nodejs` - * When prompted for Custom Setup, leave everything as default. - * Tools for Native Module - * Be sure to select the "Automatically install the necessary tools" option. - Hit on install. - - Thi will not only install Node.js, but other additional needed tools, such as Chocolatey, Python and a C/C++ compiler. A secondary installation prompt may be open for you to install thee tools. - - A terminal window will open to install the Tools, simply select the window and press any key. The windows will refresh, changing the text and explaining the tools being installed. It will prompt multiple times to install all tools. - A "Do you want to allow changes in the system" prompt may appear, choose "Yes" if that i the case. - - When prompted, always stick to defaults. - - -Set your execution policy -Set-ExecutionPolicy Bypass -Scope LocalMachine -Set-ExecutionPolicy Bypass -Scope CurrentUser - - -## Installing on **WSL** for use with **VSCode** on **Windows** - -This brief tutorial is an explanation for beginners on how to use **VSCode**, using **WSL** on **Windows**. -You may read about [**VSCode** and **WSL**](https://code.visualstudio.com/docs) if you are not familiar with them, where a clear explanation of how to install both **VSCode** and **WSL** from scratch is given. - -You may test the packaged either using **VSCode** from **Windows** or on a new **WSL** window, but to be able to debug it, it is best to use a new **WSL** window. - -Let's go to the installation. Skip any steps that you already performed. - -1. Install **VSCode** and **WSL** on your machine. - -2. Then you will need to install `Node.js` on **WSL**. - For that, run - - ```sudo apt install npm``` - - (after updating your `apt` with `sudo apt-get update`, if needed) on a **WSL** terminal. - Check the success of installation with `node -v`. - -3. As you will also use `Typescript`, you will need to install it as well, by running - - ```npm install -g typescript``` - - Check the success of installation with `tsc -v`. - -4. Then clone (or fork) the repository you want to work with. - If you are not going to debug, you may use any **Windows** directory, but if you want to debug, you will need to clone on the **WSL** file system (usually `\\wsl.localhost\Ubuntu\home\`). - The tool to manage `git` repositories is built-in inside WSL, but if you are using **Windows**, you may need to install and configure a [**GIT manager for Windows**](https://gitforwindows.org/). - - **NOTE:** I tried to debug the component from inside **VSCode** running it directly on **Windows**, but I failed, so I went for the conservative approach. - - Remember to follow the guidelines described in [**Coding standards and workflow**](../../coding-standards) regarding the use of branches and pull-requests if you are going to experiment. - -5. The next step is to open **VSCode**, and connect to a remote host to be able to run it inside **WSL**. - For that you use the `><` icon on the lower left corner of the window, and select `New WSL Window`. - The icon on the lower left corner should change to `>< WSL: Ubuntu`. - -6. The following step is to open the package folder using `Open Folder` (either from the `File` menu, the button on the `Explorer`, the link in the `Getting started` window, or by using the keyboard shortcut -- by default, `CTRL-K CTRL-O`). - -7. If needed, before proceeding with the final step, you may want to perform an update, running first - - ```npm update``` - -8. The final step is installing the component, by fetching all the dependencies. - For that, open a console (`Console -> New Console`), and run - - ```npm install``` - -Voilà. You are now ready to start exploring the package. diff --git a/src/pages/technologies/services-list/index.md b/src/pages/technologies/services-list/index.md index 568b5bc..c60c826 100644 --- a/src/pages/technologies/services-list/index.md +++ b/src/pages/technologies/services-list/index.md @@ -1,15 +1,15 @@ --- -title: List of Services +title: Services List eleventyNavigation: - key: List of Services - parent: Technology - order: 4 + key: Services List + parent: Technologies + order: 2 --- # Technologies used in **GobstonesWeb2** -**GobstonesWeb2** makes use of several services provided by third party companies, mainly **GitHub**. This attempts to be a list of such ervices for reference. +**GobstonesWeb2** makes use of several services provided by third party companies, mainly **GitHub**. This attempts to be a full list of such services for further reference. If you are an external contributor, you will probably only need to know about GitHub and **npmjs**. ------------------------------------------------------ +--------------------------------------------------------------------- ## Code Management @@ -18,24 +18,26 @@ This is a list of services that we use to manage code, automate processes, perfo ### Version Control: GitHub All the development happens in **GitHub**, and we take advantage of both their services and their community. -Every module on the project lives in a repository at GitHub. All the repositories live under the **gobstones organization**. All the source code of the projects can be found at **GitHub**, and we expect all our contributors to have an account the platform. +Every module on the project lives in a repository at GitHub. All the repositories live under the **Gobstones organization**. All the source code of the projects can be found at **GitHub**, and we expect all our contributors to have an account the platform. ### Team Management and Issue Tracking: GitHub Issues and Project Boards -**GitHub**, comes with it's own issue tracker built in. We make use of the feature by allowing not only users to report issues, but also as a tool to internally organize the development of new features, perform bug fixing and others. -Every task to perform by the team is loaded as an issue in the corresponding repository. Issues can be commented and reviewed before being worked upon. Later, one or more members of the **Core Team** are assigned to the issue for solving it. -Additionally, **GitHub** provides a feature called **GJitHub Projects**, that allows to combine several repositories and their issues into a single cohesive place, and provides a working board with all the tasks to perform, that can be adapted to be used in Scrum or Kanban methodologies. We also make heavy use of such boards to internally organize the work. +**GitHub**, comes with it's own **issue tracker** built in. We make use of the feature by allowing not only users to report issues, but also as a tool to internally organize the development of new features, perform bug fixing and others. +Every task to perform by the team is loaded as an issue in the corresponding repository. Issues can be commented and reviewed before being worked upon. Later, one or more members of the [**Core Team**](../../governance/decision-making) are assigned to the issue for solving it. + +Additionally, **GitHub** provides a feature called **GitHub Projects**, that allows to combine several repositories and their issues into a single cohesive place, and provides a working board with all the tasks to perform, that can be adapted to be used in Scrum or Kanban methodologies. We also make heavy use of such boards to internally organize the work. ### Tasks Automation and CI/CD: GitHub Actions Also as a part of **GitHub** projects can make use of **GitHub Actions** in order to perform task automation. Most modules include workflows that are automatically executed when a new commit is pushed to the repository. -Among the different actions are: +Although different projects may provide different actions, most projects provide the following actions: + * Verifying that the artifact can be build on every push. * Running the tests on every push. * Publishing the artifact to npmjs when a new tag is created. * Publishing the artifact to GitHub when a new tag is created. * Publishing the documentation to GitHub Pages when a new tag is created. -Although different projects may provide different actions. + This actions are part of our efforts to perform Continuous Integration (CI) and Continuous Deployment (CD) of all our projects. ### Publishing artifacts: Npmjs / GitHub @@ -47,18 +49,28 @@ In addition to that, extra artifact are published to **GitHub** itself, as to ap ### Documentation publishing: GitHub Pages We make use of the free **GitHub Pages** feature to publish websites for the organization repositories, and publish the documentation for each module in them. -Every time a tag for a new version is created in the repository, onw of the workflows builds the documentation page and publishes it. +Every time a tag for a new version is created in the repository, one of the workflows builds the documentation page and publishes it. ------------------------------------------------------ +--------------------------------------------------------------------- ## Communication Tools we use to keep in touch through the team. -## Community gathering: Discord +### Community gathering: Discord All the communication through the **Gobstones Community** happens officially at our [**Discord Server**](http://bit.ly/ComunidadGobstones). Although proprietary, we found Discord to be a really useful platform for communication and gathering, so we expect people to have an account at the platform if they want to join the community. Creating accounts and participating is completely free, and the Discord application can be installed at desktop computers, mobile devices, or work from as a web browser application without any installation required. -## Meeting Platform: Google Meet +### Meeting Platform: Google Meet + +For all internal meeting of the **Core Team** we use **Google Meet**. Although recently the platform provides only limited amount of time, we found that this enforces us to properly use the time on our meetings. Additionally, one is required to have a **gmail.com** account in order to join, something that all member of the team can satisfy and accept. + +--------------------------------------------------------------------- + +## Others + +Some other tools. + +### Badges -For all internal meeting of the **Core Team** we use **Google Meet**. Although recently the platform provides only limited amount of time, we found that this enforces us to properly use the time on our meetings. Additionally, one is required to have a **gmail.com** account in order to join, something at all member of the team can satisfy and accept. +All of our projects include a `README.md` file that flashes some badges for displaying the package version, the license, link to the documentation, etc. We make use of the [Shields.io Service](https://shields.io/) for the badge. diff --git a/src/pages/technologies/technology-list/index.md b/src/pages/technologies/technology-list/index.md index 694c501..c6fbac0 100644 --- a/src/pages/technologies/technology-list/index.md +++ b/src/pages/technologies/technology-list/index.md @@ -1,388 +1,272 @@ --- -title: List of Technologies +title: Technology List eleventyNavigation: - key: List of Technologies - parent: Technology - order: 4 + key: Technology List + parent: Technologies + order: 1 --- -# Technologies used in **GobstonesWeb2** +# Technology List -**GobstonesWeb2** is based on several technologies. Knowledge on some of these technologies, such as the programming language `TypeScript`, `Node.js` or `git` is mandatory, if you want to contribute to the project with code. For others you may find configuration files at the root of the project, or automatically performed actions, and although a deep knowledge on such tools is not required in order to contribute, being at least aware of the technologies in use is a must. +**GobstonesWeb2** is based on several technologies. If you want to contribute to the project with code, is mandatory for you to know some of these technologies, such as the programming language **TypeScript**, the **Node.js** platform or the **Git** version control system. For other technologies you may find configuration files at the root of the project, or you will run commands that actually run those tools under the hood, but you will probably not interact with them every-day. Although a deep knowledge on such tools is not required in order to contribute, being at least aware of the technologies in use is a must. -Most of these technologies and their configuration are totally or partially abstracted away through the [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts) module. You should read and understand how that module hides the configuration for some tools, allowing you to override the default in each project by **ejecting** the configuration files, as well as how it provides default configuration files that must be in the root of each project, but that are not meant to be modified, as we expect they are only changed through the tool by **updating** the files as a tool's action. +Most of these technologies and their configuration are totally or partially abstracted away through the [`gobstones-scripts`](https://github.com/gobstones/gobstones-scripts) module. You should read and understand how that module hides the configuration for some tools, allowing you to override the default in each project by _ejecting_ the configuration files, as well as how it provides default configuration files that must be in the root of each project, but that are not meant to be modified, as we expect them to only be changed through the tool by _updating_ the files as a tool action. -If you need help configuring the development environment, you may read the [Installation tutorial](../installation-tutorial). - ------------------------------------------------------ +--------------------------------------------------------------------- ## Language and basic environment setup These technologies are a must if you want to contribute with code in any way or are required to understand the code. - - - -### Typescript - -We use `TypeScript` as the default language for most of the development of new packages. - -`TypeScript` is a programming language based on `JavaScript`, with the addition of types, thus providing a type error detection mechanism. +### TypeScript -A good starting point to know the basics on `Typescript` is [`typescriptlang.org`](https://www.typescriptlang.org/docs/). +We use **TypeScript** as the default language for most of the development of new packages. -`TypeScript` code compiles to `JavaScript` (in a process known as transpilation), and the code produced is then run through `Node.js` (i.e. if it runs on the server or as a CLI application) or in a Web Browser (i.e. such as libraries, web libraries or react-libraries). So you need to understand the underlying way in which `JavaScript` programs execute and it's API. +**TypeScript** is a programming language based on **JavaScript**, with the addition of types, effectively transforming JavaScript into a strongly typed language that performs static type checking. **TypeScript** has structural typing, parametric typing, null types, dynamic type detection, type transformations, and many other features of advanced type systems that you should be aware of when working with it. A good starting point to know the basics on TypeScript is [typescriptlang.org](https://www.typescriptlang.org/docs/). -You may read [`developer.mozilla.org`](https://developer.mozilla.org/es/docs/Web/JavaScript) to know more on `JavaScript`. +**TypeScript code compiles to JavaScript** (in a process known as **transpilation**), and the code produced is then run through a **JavaScript Engine**. The **API** of the language is, in effect, the same as the one of **JavaScript**, so **by learning TypeScript you are also learning JavaScript**. More important, many sources of TypeScript assume knowledge of JavaScript, and do not explain the API or basic elements of the language. If you are completely new to web development, you should start by reading [developer.mozilla.org](https://developer.mozilla.org/es/docs/Web/JavaScript) to know more on **JavaScript**. -To transpile `TypeScript` code you will need the **TypeScript compiler** and then you will require an environment to run the produced `JavaScript` code, which may be the browser, `Node.js` or other. +As we mention, the code executes on a **JavaScript Engine** using a **JavaScript API**, which, depending on the type of code produced, may be different. Web applications, such as React based applications and libraries run on the **Web Browser's embedded engine**, such as **Google's V8** or **Mozilla SpiderMonkey**, and have access to typical browser elements, such as the **DOM**, but cannot make use of the underlying computer hardware, such as accessing the filesystem. Applications that run on a server, or work as a CLI application will run on **Node.js**, which works as the **JavaScript Engine** (it uses Google's V8 as engine), and these do not have access to browser elements, but can access the filesystem and hardware (through the provided **Node.js common API**). The former type is what we refer to as **Client Side Code**, while the later is **Server Side Code**, and it's important to know the difference, as each have their own available APIs. Attempting to use unavailable elements will end up in ugly and unexpected errors. Moreover, some projects, such as libraries, may produce code that can be used on the **Client Side** or the **Server Side**, so the code produces should be **Universal**. Understanding the **Client-Server Architecture** and getting acquainted with the APIs for both the browser and **Node.js** is important if you are going to start development in any of the **GobstonesWeb2** projects. -Note that you may not need to install anything, as all the typescript configuration is handled by the configuration provided through the `gobstones-script` configuration and the project itself. +Going back to **TypeScript** and the transpilation process, it's important to know that, to transpile **TypeScript** code you will need a **TypeScript Compiler** and then you will require an environment to run the produced **JavaScript** code, which may be the browser, **Node.js** or other. The **TypeScript Compiler** itself is usually executed through **Node.js**, thus making it mandatory to count with the platform on our machine, even if we are going to produce **Client Side Code**. This implies that you do not need to install the compiler itself, as all the **TypeScript** compilation, dependencies and management process is handled through `gobstones-scripts`. -Usually projects using `TypeScript` expect a configuration file for instructing the compiler how to produce the output, usually named as `tsconfig.json` and put at the root of the project. You will not find this file at most of the project, as the configuration is held and maintained internally by the `gobstones-script` library. Some projects may have the file, if they require a particular configuration that is different from the default, thus overriding the one in `gobstones-scripts`. - - - +Usually projects using **TypeScript** expect a configuration file for instructing the compiler how to produce the output (named as `tsconfig.json` and placed at the root of the project). You will not find this file at most of the projects of **GobstonesWeb2**, as the configuration is held and maintained internally by the `gobstones-scripts` library. Some projects may have the file, if they require a particular configuration that is different from the default, thus overriding the one in `gobstones-scripts`. - - - ### Node.js -We use `Node.js` to run code locally and the tooling. +We use **Node.js** to run **Server Side Code** and the run the tooling of projects. -`Node.js` is a `JavaScript` engine, that is, it allows you to run `JavaScript` code. We use `Node.js` to run the transpiled code produced by the `TypeScript` compiler. +**Node.js** is a **JavaScript engine**, that is, it allows you to run **JavaScript** code. It also provides an **API for Server Side Code**. We use **Node.js** to run the transpiled code produced by the **TypeScript** compiler. -Not only that, but mot of the tooling (such as the TypeScript compiler itself) is provided as `JavaScript` modules, that require `Node.js` or a compatible platform to run. In that sense, `Node.js` is additionally needed. So `Node.js` is needed for running tests, generating documentation, compiling the code, and so on. +Most of the tooling (such as the **TypeScript compiler** itself) is provided as **JavaScript** modules, that require **Node.js** or a compatible platform to run. In that sense, **Node.js** is needed to execute, not only the compiler, but also the rest of the tooling, like the test runner, documentation generator, etc. -Finally, all server side applications run using `Node.js` as the base server. +All **Server Side Applications** run using **Node.js** as the base server, thus making the platform not only useful for tooling, but also in deployment scenarios. -You **MUST** have the latest version installed in your system in order to code. +You **MUST** have the latest version installed in your system in order to contribute with code or run the projects from scratch. -You will find that each project have it's own `package.json` file, that will be used by `Node.js` and other tools. Most of the contributions should not touch such file. +You will find that each project have it's own `package.json` file, that will be used by **Node.js** and other tools. Most of the contributions should not touch such file. -If you want to know more on `Node.js` there are a lot of good books and tutorials on it. -A good starting point to know the basics on `Node.js` is [`nodejs.org`](https://nodejs.org/en/about/). - - - +If you want to know more on **Node.js** there are a lot of good books and tutorials on it. A good starting point to know the basics on **Node.js** is [nodejs.org](https://nodejs.org/en/about/). - - - ### npm -The `npm` package manager is used for managing dependencies and publishing libraries. - -`npm` is installed on your system when you install `Node.js` and it's a fundamental part of the tooling when developing in `TypeScript` or `JavaScript`. +The **npm** package manager is used for managing dependencies and publishing libraries. -Although `npm` is the default package manager, others may be use, such as `yarn`. Nonetheless, the project's architecture assumes a **flat hierarchy `node-modules`**. We recommend sticking with `npm` as it's the officially supported package manager. +The `npm` command line tool is typically installed on your system when you install **Node.js** and it's a fundamental part of the tooling when developing in **TypeScript** or **JavaScript**. It's what is known as a **Package Manager**, that is to say, it allows your project to make use of third party libraries, frameworks and code in general, by declaring the dependencies needed, downloading them and managing them. It also allows your library to be published so it can be used by others, even members of the **GobstonesWeb2** project. -`npm` is used to manage dependencies that the project needs for running, as well as the ones needed to build or test the project. Also, `npm` and the default `npm registry` are used to publish the packages. +> Although `npm` is the default package manager, others may be use, such +> as `yarn`. Nonetheless, the project's architecture assumes a +> **flat hierarchy `node-modules`**, so tools such as `pnpm` may not +> work as expected without proper configuration. +> +> We recommend sticking with `npm` as it's the officially supported +> package manager. You **MUST** have the latest version installed in your system in order to code. -You may find files such as `.npmrc` and `.npmignore` in the root of most projects. The files are ment to be updated only by `gobstones-scripts`. +You may find files such as `.npmrc` and `.npmignore` in the root of most projects. The files are meant to be updated only by `gobstones-scripts`. -You may need to understand how to work with `npm`. A good starting point to know the basics on `npm` is [`npmjs.com`](https://docs.npmjs.com/about-npm). - - - +You may need to understand how to work with **npm**. A good starting point to know the basics on `npm` command is [npmjs.com](https://docs.npmjs.com/about-npm). - - - ### Visual Studio Code -We use **Visual Studio Code** (`VSCode`) as the default IDE. +We use **Visual Studio Code** (**VSCode**) as the default IDE. -One important addition for helping on the development is the IDE (Integrated Development Environment). There are many good ones, but we mostly make use of `VSCode`. +One important addition for helping on the development is the IDE (Integrated Development Environment). There are many good ones, but we mostly make use of **VSCode**. Most projects include a `.vscode` folder that, once a project is open in the IDE, some extensions and configurations are recommended by the environment. -You **MAY** choose to use any IDE of your choice, as long as the IDE, but we recommend sticking with IDEs that integrate with `Prettier` or at least understand the configuration provided through `EditorConfig`. If on doubt, we recommend you stick with `VSCode`. +You **MAY** choose to use any IDE of your choice, but we recommend sticking with IDEs that integrate with **Prettier** or at least understand the configuration provided through **EditorConfig**. If on doubt, we recommend you stick with `VSCode`. -A good starting point to know the basics on `VSCode` is [`code.visualstudio.com`](https://code.visualstudio.com/docs). - - - +A good starting point to know the basics on **VSCode** is [code.visualstudio.com](https://code.visualstudio.com/docs). - - - -### git and GitHub +### Git and GitHub -We use *git** as the code's VCS and GitHub as server and platform. +We use **Git** as the code's **VCS** and **GitHub** as server and platform. -A VCS (Version Control System) allows for code history tracking and management, as well as simplifying code sharing, publishing and others. We use `git`, which is one of the most popular choices. +A **VCS** (**Version Control System**) allows for code history tracking and management, as well as simplifying code sharing, publishing and others. We use **Git**, which is one of the most popular choices. -The `git` tool bases itself in the concept of repositories, and one such repository acts as the single source of truth for any project. We use `GitHub` as a server to publish such a repository for all our projects. +The `git` command line is the main command for **Git**. Git bases itself in the concept of repositories, and one such repository acts as the single source of truth for any project. We use [**GitHub**](https://github.com) as a hosting platform to publish such repositories for all our projects. -You **MUST** have `git` installed on your system in order to contribute, as well as a `GitHub`'s account. +You **MUST** have `git` installed on your system in order to contribute, as well as a **GitHub** account. -If you do not have a GitHub account, you may create one at [github.com](https://github.com). If you do not know what `git` is, there are many books available, but you may start at [git-scm.com](https://git-scm.com) +If you do not have a GitHub account, you may create one at [github.com](https://github.com). If you do not know what **Git** is, there are many books available, but you may start at [Git-scm.com](https://git-scm.com) Configuration for `git`, with files such as `.gitignore` is already present in all projects, and it's handled through updates of `gobstones-scripts`, so you should not modify such file. -In addition to basic `git`, we make use of features provided by `GitHub`, such as the `GitHub Actions` (for Continuous Integration) and `GitHub Pages` (For Documentation publishing), as well a handling **Issues** and **Pull Requests** through their platform. +In addition to basic **Git** management through the command, we make use of features provided by **GitHub**, such as the **GitHub Actions** (for Continuous Integration) and **GitHub Pages** (For Documentation publishing), as well a handling **Issues** and **Pull Requests** through their platform. You may read more about it in the [Services List Section](../services-list/). You may also find a `.github` folder at the root of mot projects, that holds configuration for some of these platform's tools. -Also, if you have been using `git` in the past, you may find a slight different behavior in how it works on our project. This is explain by the addition of some tools added to enforce **semantic-commits**. For more information, read about `Husky`, `Commit Lint` and `Commitizen` in the **Git control** subsection of this document. - - - - ------------------------------------------------------ +Also, if you have been using the `git` command in the past, you may find a slightly different behavior in how it works on our project. This is explained by the addition of some tools added to enforce **semantic-commits**. For more information, read about **Husky**, **Commit Lint** and **Commitizen** in the **Git Control** subsection of this document, and then read the [Commit Conventions Section](../../coding/commit-conventions). +--------------------------------------------------------------------- ## Building and automating The tools in this section are used for either orchestrating the execution of development actions, generating binary or exportable builds. - - - - ### nps -We use `nps` as the task manager. +We use `nps` command as the task manager. -To define and execute custom scripts within `Node.js`, running all the tooling in a simple fashion, we use `nps` (Node Package Scripts). -`nps` it's a task manager or task executor (in the same fashion as `grunt` or `gulp`). +To define and execute custom scripts within **Node.js**, and running all the tooling in a simple fashion, we use **nps** (**Node Package Scripts**), the `nps` command line tool. **nps** is a task manager or task executor (in the same fashion as `grunt` or `gulp`). It's a little dated, but we found elegance in it's simplicity. -The good thing about `nps` is that it does not require knowledge of complex models and tools, but it's just a one step up on manually running the command through the terminal one by one. `npm run` runs the commands in "scripts" defined in package.json. `nps` is useful when the commands needed to run exceed some simple commands. In all projects, running `npm start` runs the help on all defined `nps` commands. +The good thing about nps is that it does not require knowledge of complex models and tools, as it uses the same principle that it's embedded in npm through the `scripts` section declared in the `package.json` file. The `nps` tool just takes it one step further, allowing to configure the scripts to run in a separate file. `nps` is useful when the scripts needed to run exceed some simple strings, or when there are too many of them. It additionally provides a way to list all commands, declare documentation for them, etc. In all projects of the **GobstonesWeb2** platform, running `npm start` runs the help on all defined `nps` commands that you may execute. -The configuration file for `nps`, `package-scripts.json` is abstracted away by `gobstones-scripts` by default, although you can eject it if you need to change the behavior of any task. This is a simple json file, listing all the possible tasks to run, and the code each of them will run on the terminal, along some description. +The configuration file for `nps`, `package-scripts.js` is, by default, abstracted away by `gobstones-scripts`, although you can eject it if you need to change the behavior of any task. This is a simple js file that exports a single object declaring the configuration of all the possible scripts to run, and the code each of them will execute on the terminal. -Some predefined tasks are configured, such as building the application, running the tests, building and serving the documentation, and linting. Most simple calls are also present in the `scripts` section of each project's `package.json`, but you may run any task using `npm start` followed by the task to run. +The default file included in `gobstones-scripts` provides some basic actions, such as executing in development mode, building the application, running the tests, building and serving the documentation, linting the files, etc. You may run any task using `npm start` followed by the task to run, or simply run `npm start` to get the full list of scripts available. -Additionally, tasks in the configuration for most of the projects make use of some helper tasks exported by the `gobstones-scripts` module, such as `serially` or `concurrently`. +Additionally, if you find ejected configuration files in any project, you may observe that the file makes use of some helper tasks exported by the `gobstones-scripts` module, such as `serially` or `concurrently`. The `gobstones-scripts` module provides such tasks as to simplify the declaration of these files. -Again, basic configuration has already been provided, and there is not much you need to do to start using it than downloading the projects and installing the dependencies. Nonetheless, you may read more about `nps` in [`nps at npmjs`](https://www.npmjs.com/package/nps). - - - +Again, basic configuration has already been provided, and there is not much you need to do to start using it other than downloading the projects and installing the dependencies. Nonetheless, you may read more about **nps** at [their npmjs page](https://www.npmjs.com/package/nps). - - - ### Rollup -We rely on `rollup.js` to bundle the code of the project libraries. +We rely on **Rollup.js** to bundle the code of the project libraries. -Most modern projects rely in some bundler that packages all the code into a single distributable file. There are many bundlers you may be aware of, like `webpack`, `esm` or others. We chose `rollup` because it's can create efficient and optimized bundles for both the web and CLI applications, and it's specially useful for libraries. +Most modern projects rely in what is known as a **bundler** that packages all the code into a single distributable file. There are many bundlers you may be aware of, like `webpack`, `esm` or others. We chose **Rollup** because it can create efficient and optimized bundles for both the web and CLI applications, and it's specially useful for libraries. -`rollup` also has many plugins, useful to allow code to pack additional filetypes, such as JSON, css, images or others, minifying or obfuscating the code. One such plugin calls the `TypeScript compiler`, and compile the code, avoiding the need to call the compiler directly. You will find that most project use this configuration instead of calling the compiler. +The `rollup` command also has many plugins that extend it's capabilities. Some allow us to pack additional filetypes, such as JSON, CSS, images, etc., others allow to minify or obfuscate the produced code. One such plugin calls the **TypeScript compiler**, and compiles the code. This avoids the need to call the compiler directly, and you will find that most projects in **GobstonesWeb2** use this configuration instead of calling the compiler manually as a first step -You do not need to know rollup in detail unless you need to change the way a project is bundled or compiled. The configuration file, `rollup.config.js` is hidden by the `gobstones-script` module. You may always overwrite the default by **ejecting** the configuration files. +You do not need to know `rollup`` in detail unless you need to change the way a project is bundled or compiled. The configuration file,`rollup.config.js` is hidden by the `Gobstones-scripts` module. You may always overwrite the default by **ejecting** the configuration files. -A good starting point to know the basics on `rollup.js` is [`rollupjs.org`](https://rollupjs.org/). - - - +A good starting point to know the basics on **Rollup.js** is [rollupjs.org](https://rollupjs.org/). - - - ### Vite -We rely on `Vite` to bundle the code of the project react libraries. - -`vite` is another bundler. It's focused on bundling web applications (not libraries), and we use it to bundle the react libraries as full application for testing and development. The final bundling for distribution is still performed by `Rollup`. +We rely on **Vite** to bundle the code of the project's React libraries. -You may find a `vite.config.ts` file with the configuration in the root of the react library projects. You should not change these configuration files, unless through updated of `gobstones-scripts`. +The `vite` tool is another **bundler**. It's focused on bundling web applications (not libraries), and uses Rollup under the hood. We use Vite to execute other tooling, such as **StoryBook** for developing **React** libraries. The final bundling for distribution is still performed by **Rollup**. -You will probably not need to know much about may read about Vite in [`vitejs.dev`](https://vitejs.dev). - - - +You may find a `vite.config.ts` file with the configuration in the root of the React library projects. You should not change these configuration files, unless through the **update** command of `gobstones-scripts`. ------------------------------------------------------ +You will probably not need to know much about `vite`, as we barely make use of it, but if interested, you may read about it in [`vitejs.dev`](https://vitejs.dev). +--------------------------------------------------------------------- ## Code format and style The tools in this section are used to guarantee the format and style consistency of the code along all projects. - - - - ### Prettier -We use `Prettier` to provide a uniform coding formatting through all projects. +We use **Prettier** to provide a uniform coding formatting through all projects. -To ensure uniformity in coding format, we integrate the opinionated code formatter `Prettier`. It allows to set a standardized set of formatting rules, such as indentation type, max length of lines, line endings and others. +To ensure uniformity in coding format, we integrate the opinionated code formatter **Prettier**. It allows to set a standardized set of formatting rules, such as indentation type, max length of lines, line endings and others. -Note that prettier does not enforce the format, but rather allows you to reformat your code using the provided configuration. The IDE uses this to automatically reformat your code on saving a file. Also, `ESlint` integrates with `Prettier`, to verify that the format is compliant with the prettier configuration. +Note that prettier does not enforce the format, but rather allows you to reformat your code using the provided configuration. The IDE uses this to automatically reformat your code on saving a file. Also, **ESlint** integrates with **Prettier** to verify that the format is compliant with the Prettier configuration. -The `Prettier` configuration files are present at the root of each project, as `.prettierrc` and `.prettierignore`, and should only be modified for all projects, through an update of `gobstones-scripts`. +The **Prettier configuration files** are present at the root of each project, as `.prettierrc` and `.prettierignore`, and should only be modified through the use of the **update** command of `gobstones-scripts`, as we aspire that all projects share a common format. -You do not need to know much about `Prettier` to start using it in the project, as all the configuration has already been done for you, that is, unless you use a different IDE than `VSCode`. If you want to learn more about the tool, you may read [`prettier.io`](https://prettier.io/). - - - +You do not need to know much about **Prettier** to start using it in the project, as all the configuration has already been done for you, and any good code editor will detect the configuration and use it automatically. If you want to learn more about the tool, you may read [`prettier.io`](https://prettier.io/). - - - ### EditorConfig -We also include an `EditorConfig` file in every project. +We also include an **EditorConfig** file in every project. -Although `Prettier` is a great tool for code formatting, some IDEs do not play along with prettier, or they do not do it by default. To support more IDEs and code editors we have included an `EditorConfig` file in each project. +Although **Prettier** is a great tool for code formatting, some IDEs do not play along with Prettier, or they do not do it by default. To support more IDEs and code editors we have included an **EditorConfig** file in each project. -The `EditorConfig` file, `.editorconfig` contains basic formatting configuration to tell the code editor how you require your files to be treated, such as line endings, tab width and so on. +The **EditorConfig** file, `.editorconfig` contains basic formatting configuration to tell the code editor how you require your files to be treated, such as line endings, tab width and so on. This configuration should always match the one in your **Prettier configuration files**, and should be the same through all projects, and as such, only should be changed through the **update** command of `gobstones-scripts`. -This configuration should always match the one in your `Prettier` configuration, and should be the same through all projects, and as such, only should be changed through an update of `gobstones-scripts`. +Again, you don't need to know much about **EditorConfig**, but it's a simple enough tool to understand by reading the provided documentation at [`editorconfig.org`](https://editorconfig.org/). -Again, you don't need to know much about `EditorConfig`, but it's a simple enough tool to understand by reading the provided documentation at [`editorconfig.org`](https://editorconfig.org/). - - - - - - - ### ESLint -`ESLint` as a linter for maintaining coding standards. +**ESLint** as a linter for maintaining coding standards. -Although `Prettier` provides formatting configuration, code styling is enforced through `ESLint`. This linter provides configuration that determine things such as the order in which methods should be declared, which are valid identifiers for a variable, where you should open and close your braces and other language aware style configuration. +Although **Prettier** provides formatting configuration, code styling is enforced through **ESLint**. This linter provides configuration that determine things such as the order in which methods should be declared, which are valid identifiers for a variable, where you should open and close your braces and other language aware style configuration. It statically analyzes the code for common errors, stylistic issues, and potential pitfalls, thus providing actionable feedback to fix such problems, ensuring the code's quality and reliability. -`ESLint` uses the concept of plugins and templates, of which we use many to enforce some particular configuration. The linter is run by default before any test, and in case of style errors, the tests cannot pass. +**ESLint** uses the concept of plugins and templates, of which we use many to enforce some particular configuration. By default, the linter is run by default before any test, and in case of style errors, the tests process fails. The linter can also be executed on it's own. -You will find the `ESLint` configuration file, `.eslintrc` at the root of every project. Again, it should not be changed except through updates of `gobstones-scripts`. +You will find the **ESLint configuration file**, `.eslintrc` at the root of every project. Again, it should not be changed except through the **update** command of `gobstones-scripts`. You will usually not require changing these rules, but to understand the basic idea behind the linter you may read the documentation at [`eslint.org`](https://eslint.org/). - - - ------------------------------------------------------ +--------------------------------------------------------------------- ## Documentation and Testing This tools are used to test code through unit testing or functional testing, or to generate project documentation. - - - ### TypeDoc -We use `TypeDoc` to generate the project documentation. +We use **TypeDoc** to generate the project documentation. -As a way to generate documentation, the `TypeDoc` tool reads the `TypeScript` source files, parses comments contained within them, and creates API documentation for a more comprehensive and well-structured documentation of the project. +As a way to generate documentation, the `typedoc` tool reads the TypeScript source files, parses comments contained within them, and creates API documentation for a more comprehensive and well-structured documentation of the project. -You **SHOULD** be aware of basic practices for documentation, as code without documentation will not be accepted as contribution. +You **SHOULD** be aware of basic practices for documentation, as code without documentation will not be accepted as contribution. You can read more about it at the [Writing Documentation Section](../../coding/writing-documentation). -You may find that the configuration file `typedoc.js` is not present at the root of most projects, as it has been abstracted by the `gobstones-scripts` tool. If you require some particular configuration, you may **eject** the file into the project root. +You may find that the configuration file `typedoc.config.js` is not present at the root of most projects, as it has been abstracted by the `gobstones-scripts` tool. If you require some particular configuration, you may **eject** the file into the project root. A good starting point to know the basics on `TypeDoc` is [`typedoc.org`](https://typedoc.org/guides/overview/). - - - - - - ### StoryBook -We use `StoryBook` to generate a runnable version of react components. +We use **StoryBook** to generate a runnable version of React components. -`StoryBook` is a tool for generating a testing/visualization page for a web component or react components. It allows you to visualize, modify and test a component easily. +**StoryBook** is a tool for generating a testing/visualization page for a web component or React components. It allows you to visualize, modify and test a component easily. -We use `StoryBook` to run in development mode when developing components, as well as generating a demo of the component for the documentation page published. +We use **StoryBook** to run in development mode when developing components, as well as generating a demo of the component for the documentation page published. You will see a `.storybook` folder, as well as a `stories` folder in each project containing components. That last folder requires user modification if new components are added or if current components are modified. -In that sense, you **SHOULD** be aware of how these stories work. We recomend you to start by reading the documentation at [storybook.js.org](https://storybook.js.org). - - - +In that sense, you **SHOULD** be aware of how these stories work. We recommend you to start by reading the documentation at [StoryBook.js.org](https://storybook.js.org). - - - ### Jest -We use `Jest` for testing. +We use **Jest** for testing. -`Jest` will handle running, and managing test suites. It works with `TypeScript` code, providing a comprehensive set of tools and features to simplify the process of writing and maintaining tests. +**Jest** will handle running, and managing test suites. It works with TypeScript code, providing a comprehensive set of tools and features to simplify the process of writing and maintaining tests. -You **SHOULD** learn how to properly create and run tests, as code that is not properly tested or breaks existing tests will not be accepted. +You **SHOULD** learn how to properly create and run tests, as code that is not properly tested or breaks existing tests will not be accepted. Also, you need to be aware of the styling practices we use when writing tests, so you should check the [Testing Section](../../coding/testing). You will fin that the `jest.config.js` file is not at the root of the library for most projects, as it's abstracted away by the `gobstones-scripts` module. You can always overwrite the configuration by **ejecting** the file. A good starting point to know the basics on `Jest` is [`jestjs.io`](https://jestjs.io/). - - - - ------------------------------------------------------ +--------------------------------------------------------------------- ## Git control -This tools are used to manage the code's version control, git, by providing git hooks and validating commit messages. +This tools are used to manage the code's version control, Git, by providing Git hooks and validating commit messages. - - - ### Husky -`Husky` is used to provide and trigger `git hooks`. +**Husky** is used to provide and trigger **Git Hooks**. -Git hooks are a way to provide automatic behavior when some particular git action is performed, such as a commit or a push. `Husky` provides a way to create such hooks in our projects in an eay fashion. +**Git Hooks** are a way to provide automatic behavior when some particular Git action is performed, such as a commit or a push. **Husky** provides a way to create such hooks in our projects in an easy fashion. -In most projects you will find a `.husky` folder that contains the hooks to execute, as well as some other configurations. We use the hooks to validate commits and ensure **conventional commits**, as well as to automatically generate some files, such as the CHANGELOG. You will not likely have to change this, as it's intended to be changed through updates of `gobstones-scripts`. +In most projects you will find a `.husky` folder that contains the hooks to execute, as well as some other configurations. We use the hooks to validate commits and ensure **Conventional Commits**, as well as to automatically generate some files, such as the `CHANGELOG.md` file. You will not likely have to change this, as it's intended to be changed through the **update** command of `gobstones-scripts`. -You will usually not need to know much about `Husky`, but you may find their documentation useful by going to [typicode.github.io/husky](https://typicode.github.io/husky) - - - - +You will usually not need to know much about `Husky`, but you may find their documentation useful by going to [typicode.github.io/husky](https://typicode.github.io/husky). It may also be useful to know more about the **Git hooks**, which you can read about at [The Git Book](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) and get a full list of the hooks available at [The Git Docs for githooks](https://git-scm.com/docs/githooks). - - - ### Commitizen -`Commitizen` is used to enforce a particular format in commit messages. +**Commitizen** is used to enforce a particular format in commit messages. When having to write a commit message it's tempting to provide a minimal description and just push the code. We attempt to follow **conventional commits**, and to help enforce proper messages, we use `Commitizen`. This tool runs through a `Husky` hook whenever there's a commit (except the `--no-verify` flag is used or you are amending a commit). `Commitizen` provides a simple prompt with different questions, and once all are answered it will present you the fully generated commit message. The questions presented will guide you through defining a proper conventional commit message. You may always modify the message at the end of the process if needed. -You will find a `.czrc` file with the `Commitizen` configuration at the root of most projects, although changing the defaults is not recommended, as it's intended to be changed through updates of `gobstones-scripts`. +You will find a `.czrc` file with the **Commitizen** configuration at the root of most projects, although changing the defaults is not recommended, as it's intended to be changed through updates of `gobstones-scripts`. -You do not need to know much about `Commitizen`, but you can read their documentation at [commitizen at npmjs](https://www.npmjs.com/package/commitizen) - - - - +You do not need to know much about **Commitizen**, but you can read their documentation at [their npmjs page](https://www.npmjs.com/package/commitizen) - - - ### CommitLint -`CommitLint` is used to lint the commit messages and ensure they follow the conventional commit structure. - -As `Commitizen` only guides you through creating a commit message with proper conventional commit style, but you are allowed to modify the message later, `CommitLint` is used to validate that the commit message actually uses the conventional commit style. +**CommitLint** is used to lint the commit messages and ensure they follow the **Conventional Commit** structure. -This tool runs as a `Husky` hook after a commit message has been redacted, and just before the actual commit. If it finds any error in the style of the commit, it will abort the commit, else, the commit will pass and be performed. +As **Commitizen** only guides you through creating a commit message with proper conventional commit style, but you are allowed to modify the message later, **CommitLint** is used to validate that the commit message actually uses the conventional commit style. -You will find a `commitlint.config.js` file with the `CommitLint` configuration at the root of most projects, although changing the defaults is not recommended, as it's intended to be changed through updates of `gobstones-scripts`. +This tool runs as a **Husky** hook after a commit message has been redacted, and just before the actual commit. If it finds any error in the style of the commit, it will abort the commit, else, the commit will pass and be performed. -You do not need to know much about `CommitLint`, but you can read their documentation at [commitlint.js.org](https://commitlint.js.org/#/) +You will find a `commitlint.config.js` file with the **CommitLint** configuration at the root of most projects, although changing the defaults is not recommended, as it's intended to be changed through the **update** command of `gobstones-scripts`. - - - +You do not need to know much about CommitLint, but you can read their documentation at [commitlint.js.org](https://commitlint.js.org/#/) ------------------------------------------------------ +--------------------------------------------------------------------- -To learn about the coding standards and workflow for the mentioned technologies and GobstonesWeb2 in general [consult coding standards and workflow section](../../coding-standards). +To learn about the coding standards and workflow for the mentioned technologies and **GobstonesWeb2** in general you may read the [Coding Section](../../coding). diff --git a/src/templates/includes/footer.html b/src/templates/includes/footer.html index a2998ba..c7541f9 100644 --- a/src/templates/includes/footer.html +++ b/src/templates/includes/footer.html @@ -1,2 +1,10 @@ diff --git a/test/verify-links.js b/test/test-runner.js similarity index 68% rename from test/verify-links.js rename to test/test-runner.js index f1b899a..cc47280 100644 --- a/test/verify-links.js +++ b/test/test-runner.js @@ -2,8 +2,10 @@ const fs = require('fs'); const path = require('path'); const process = require('process'); const { rimraf } = require('rimraf'); -const { execSync } = require('child_process') -const chalk = require('ansi-colors') +const { execSync } = require('child_process'); +const chalk = require('ansi-colors'); + +const verifyLinks = require('./verify-links.test'); function switchCurrentLocationToProjectRoot() { let dir = process.cwd(); @@ -17,42 +19,60 @@ function switchCurrentLocationToProjectRoot() { } } -function generateLinkinatorReport() { - console.log('Building the site...'); - rimraf('./dist'); +function buildProject() { + rimraf(verifyLinks.distFolder); execSync('npx @11ty/eleventy'); - console.log('Analizying links...'); - execSync('npx linkinator "./dist/**/*.html" --format json > ./dist/test-results.json'); + execSync(`npx linkinator "${verifyLinks.distFolder}/**/*${verifyLinks.distFileExtension}" --format json > ${verifyLinks.fileLocation}`); execSync('sleep 1'); - const results = JSON.parse(fs.readFileSync('./dist/test-results.json')); - rimraf('./dist'); - return results; } -function processResultsIntoTestStatus(results) { +function cleanProject() { + rimraf(verifyLinks.distFolder); +} + +function generateLinkinatorReport() { + const results = JSON.parse(fs.readFileSync(verifyLinks.fileLocation)); let allPassed = true; const linksPerDoc = {}; const documents = []; for (const link of results.links) { + const distNoStarting = verifyLinks.distFolder.replace('./', ''); + // Avoid unnamed file links if (!link.parent) continue; // Avoid navigation links, global style and others to be considered if ( - link.parent === 'dist/index.html' && - !link.url.startsWith('dist') && + link.parent === `${distNoStarting}/index.html` && + !link.url.startsWith(distNoStarting) && !link.url.match(/^(?:[a-z+]+:)?\/\//i) ) { continue; } // Process link - const docName = link.parent.replace('dist/', './src/pages/').replace('.html', '.md'); + const docName = + link.parent + .replace(`${distNoStarting}/`, `${verifyLinks.srcFolder}/`) + .replace(verifyLinks.distFileExtension, verifyLinks.srcFileExtension); let url = link.url; if (!url.match(/^(?:[a-z+]+:)?\/\//i)) { url = path.relative(path.dirname(link.parent), link.url); if (!url.startsWith('.')) { - url = './' + url; + url = `./${url}`; + } + } + // Eliminate excluded urls + let isExcluded = false; + for (const exclusion of verifyLinks.excludedUrls) { + if (url.startsWith(exclusion)) { + isExcluded = true; + break; } } + if (isExcluded) { + continue; + } + + // Add to the results if (!linksPerDoc[docName]) { linksPerDoc[docName] = { passed: true, links: [] }; } @@ -62,9 +82,17 @@ function processResultsIntoTestStatus(results) { status: link.status, state: link.state }); - // Fix errors due to permissions in github, as we want to link to - // private repos - if (url.startsWith('https://github.com') && link.status !== 200) { + + // Ignored links are always marked as 200 + let isIgnoredError = false; + for (const exclusion of verifyLinks.ignoreErrorUrls) { + if (url.startsWith(exclusion)) { + isIgnoredError = true; + break; + } + } + + if (isIgnoredError && link.status !== 200) { linksPerDoc[docName].links[ linksPerDoc[docName].links.length-1].status = 200; linksPerDoc[docName].links[ linksPerDoc[docName].links.length-1].state = 'OK'; } else { @@ -132,9 +160,12 @@ function printTestResults(testStatus) { function runTests() { switchCurrentLocationToProjectRoot(); - let testStatus = processResultsIntoTestStatus(generateLinkinatorReport()); + buildProject(); + + let testStatus = generateLinkinatorReport(); printTestResults(testStatus); - process.exit(testStatus.passed ? 0 : 1); + cleanProject(); + process.exitCode = testStatus.passed ? 0 : 1; } runTests(); diff --git a/test/verify-links.test.js b/test/verify-links.test.js new file mode 100644 index 0000000..4a6650c --- /dev/null +++ b/test/verify-links.test.js @@ -0,0 +1,9 @@ +module.exports = { + fileLocation: './dist/linkinator.json', + distFolder: './dist', + distFileExtension: '.html', + srcFolder: './src/pages', + srcFileExtension: '.md', + excludedUrls: [], + ignoreErrorUrls: ['https://github.com', 'https://gobstones.github.io'], +}