diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 00000000..5da2acb8 --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,105 @@ +# Design decisions + +When we create software, we often have to decide between multiple ways to realize our vision. When maintaining a project, we may think of a "better" way to do things. At this point, we must be able to quickly decide whether: +- The new idea was one of the considered options but was discarded for some reason, +- The new idea was not considered, but some constraint makes it an incorrect solution, +- The new idea was not considered, and it is indeed better than the implemented solution. + +Deciding between these situations can be very hard when no context is available, especially in teams which make decisions during meetings, which leave no trail. There are multiple ways to increase available context for future decisions: writing more comprehensive documentation comments, adding details in the Git history, and writing detailed documents describing the decisions. + +This directory implements the latter pattern, also called Architecture Decision Records ([learn more](https://adr.github.io/)). Each document describes a single decision and considered alternatives. + +[TOC] + +## Which decisions should be recorded? + +Whenever there is a chance that multiple solutions fit a problem, or when the plan has to change because the originally-imagined solution turned out to be unfitting. As a rule of thumb, if a reviewer asks you why you did something one way instead of another, it's probably worth recording this decision. + +However, not all decisions are worth adding to this directory: +- If a decision is specifically localized to one file (e.g. to one function, to one class), a regular comment at that place is more useful because it is better co-located. +- If a decision is a one-time thing and has no consequences for the future, describing it in the commit description (or merge request description) is more efficient. For example, putting in place a new workflow, which has its own documentation file in the repository, doesn't require a record, as it would otherwise mostly be a duplicate of the chosen workflow. + +These kinds of decisions likely require a new record: +- Deciding between two alternative ways to do things that are very similar. +- Decisions that affect more than one file (e.g. an entire package, an entire module, the entire project…). +- Decisions that have consequences on the future (e.g. future maintainers should continue following them to keep coherence). + +## Creating a new record + +Here is a template for new records: +```markdown +# + +| | | +|---------------|----------| +| Status | <Status> | +| Discussion | <Link> | +| Superseded by | <link·s> | +| Relates to | <Link·s> | + +<Short description> + +[TOC] + +## The problem + +## Constraints + +## Considered solutions + +## Selected solution +``` + +The following describes all the fields of the template and what they should be filled in with. + +**Status:** + +[![Status: draft](https://badgen.net/static/Status/draft/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision is a draft. It should not yet be followed. The field "Discussion" should be present. + +[![Status: active](https://badgen.net/static/Status/active/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision is active and should be followed in all new code. When editing existing code which doesn't follow this decision, consider rewriting it so it does. + +[![Status: archived](https://badgen.net/static/Status/archived/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision was active, but isn't anymore. New code isn't required to follow it. Existing code may or may not still follow it, and no particular migration efforts are required. + +[![Status: superseded](https://badgen.net/static/Status/superseded/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision was active, but was superseded by another decision. New code should follow the new decision. Existing code, when possible, should be migrated to follow the new decision. The field "Superseded by" should be present. + +**Discussion:** +When in "draft" status, links to an issue, a merge request, or some other type of document that allows comments. Any questions from the discussion that isn't answered by the record should be added to the record. When a record graduates and becomes active, the discussion link may remain for archival purposes (an active record is not subject to discussion, except when creating a new superseding record). + +**Superseded by:** +Links to one or more record which overturn the current record. Only presents when the status is "superseded". + +**Related to:** +Links to other records which have a related subject. + +**The problem.** +Exhaustive and precise description of the problem·s to solve. + +**Constraints.** +Additional constraints that are not intrinsic to the problem but may still impact decision-making. For example, a constraint on development time. + +**Considered solutions.** +Each considered solution should have its own section, containing: +- A description of what it would entail, +- A list of advantages compared to other solutions, +- A list of disadvantages compared to other solutions. + +The advantages and disadvantages may be subjective, as long as they are appropriate in the context of the problem. For example, "no one in the team has used this technology" is an appropriate disadvantage to using it, even if it seems completely appropriate otherwise. + +The selected solution should be included in this section, with the same content as all other alternatives. + +**Selected solution.** +Describes the selected solution in more details, and explains why it was selected (especially if other solutions have advantages that this one doesn't). + +## How are decision records modified? + +Unless to edit their status, records should almost never be edited. + +## What happens when a decision is overturned? + +If a decision is overturned, a new record should be created with the new decision, linking to the previous one. The previous one should be marked as Superseded. + +## When are decision records deleted? + +Decision records may only be deleted when **no content from to the repository whatsoever** uses them anymore, and **no future content should follow them**. At this point, and only at this point, are they truly useless, and thus worthy of deletion. + +As long as a single piece of code, static resources or anything else committed to the repository follows a design decision, it should remain in the repository as well. -- 2.51.2 From c3d1c7200c9db5eb63bbbfef7e67602e46808e69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 19:34:49 +0200 Subject: [PATCH 02/10] docs: Link useful external guides in the ADR file --- docs/design/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/design/README.md b/docs/design/README.md index 5da2acb8..3eccf970 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -50,6 +50,8 @@ Here is a template for new records: ## Selected solution ``` +Useful external links: [How to write ADRs](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html), [How to review ADRs](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html). + The following describes all the fields of the template and what they should be filled in with. **Status:** -- 2.51.2 From 9856e59285f06f533690e4d3dffae7e3e90dd3f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 19:53:33 +0200 Subject: [PATCH 03/10] build(idea): Run configuration to run the mkdocs website locally --- .../Documentation_website.xml | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .idea/runConfigurations/Documentation_website.xml diff --git a/.idea/runConfigurations/Documentation_website.xml b/.idea/runConfigurations/Documentation_website.xml new file mode 100644 index 00000000..1c2fb07b --- /dev/null +++ b/.idea/runConfigurations/Documentation_website.xml @@ -0,0 +1,28 @@ +<component name="ProjectRunConfigurationManager"> + <configuration default="false" name="Documentation website" type="docker-deploy" factoryName="docker-image" server-name="Docker"> + <deployment type="docker-image"> + <settings> + <option name="imageTag" value="squidfunk/mkdocs-material" /> + <option name="containerName" value="" /> + <option name="portBindings"> + <list> + <DockerPortBindingImpl> + <option name="containerPort" value="8000" /> + <option name="hostPort" value="7999" /> + </DockerPortBindingImpl> + </list> + </option> + <option name="volumeBindings"> + <list> + <DockerVolumeBindingImpl> + <option name="containerPath" value="/docs" /> + <option name="hostPath" value="$PROJECT_DIR$/docs/website" /> + <option name="readOnly" value="true" /> + </DockerVolumeBindingImpl> + </list> + </option> + </settings> + </deployment> + <method v="2" /> + </configuration> +</component> \ No newline at end of file -- 2.51.2 From e1eea66eeae2979ea9395f6e7fe9b23cc38b314f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 19:59:24 +0200 Subject: [PATCH 04/10] docs(website): Fix the edition link --- docs/website/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 787b9ef3..a8c5edb5 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -37,4 +37,4 @@ theme: edit: material/pencil view: material/eye -edit_uri: edit/main/docs/website +edit_uri: edit/main/docs/website/docs -- 2.51.2 From 1aa7b3aa2f7064d063794c12045aeb40f2bece14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:21:19 +0200 Subject: [PATCH 05/10] docs(website): Add OpenSavvy logo --- docs/website/docs/assets/logo.svg | 127 ++++++++++++++++++++++++++++++ docs/website/mkdocs.yml | 2 + 2 files changed, 129 insertions(+) create mode 100644 docs/website/docs/assets/logo.svg diff --git a/docs/website/docs/assets/logo.svg b/docs/website/docs/assets/logo.svg new file mode 100644 index 00000000..3c87a670 --- /dev/null +++ b/docs/website/docs/assets/logo.svg @@ -0,0 +1,127 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:xlink="http://www.w3.org/1999/xlink" + width="400" + height="400" + viewBox="0 0 400 400" + version="1.1" + id="svg1" + xmlns="http://www.w3.org/2000/svg"> + <defs + id="defs1"> + <linearGradient + id="linearGradient6"> + <stop + style="stop-color:#4d249a;stop-opacity:1;" + offset="0" + id="stop5"/> + <stop + style="stop-color:#972aa7;stop-opacity:1;" + offset="1" + id="stop6"/> + </linearGradient> + <linearGradient + id="linearGradient1"> + <stop + style="stop-color:#5226a2;stop-opacity:1;" + offset="0" + id="stop1"/> + <stop + style="stop-color:#852da0;stop-opacity:1;" + offset="1" + id="stop2"/> + </linearGradient> + <linearGradient + id="linearGradient13"> + <stop + style="stop-color:#0b8bea;stop-opacity:1;" + offset="0" + id="stop13"/> + <stop + style="stop-color:#11d2ed;stop-opacity:1;" + offset="1" + id="stop14"/> + </linearGradient> + <linearGradient + xlink:href="#linearGradient13" + id="linearGradient14" + x1="241.17003" + y1="283.41473" + x2="242.69476" + y2="105.93424" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1.2715214,0,0,1.2715214,-52.39746,-43.00102)"/> + <linearGradient + xlink:href="#linearGradient1" + id="linearGradient2" + x1="156.07582" + y1="3.1215208" + x2="251.95094" + y2="399.10815" + gradientUnits="userSpaceOnUse"/> + <linearGradient + xlink:href="#linearGradient13" + id="linearGradient3" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1.2715214,0,0,1.2715214,-49.761695,-40.852208)" + x1="241.17003" + y1="283.41473" + x2="242.69476" + y2="105.93424"/> + <linearGradient + xlink:href="#linearGradient6" + id="linearGradient5" + gradientUnits="userSpaceOnUse" + x1="156.07582" + y1="3.1215208" + x2="251.95094" + y2="399.10815" + gradientTransform="matrix(1.4200707,0,0,1.4200707,-84.053693,-83.525091)"/> + </defs> + <!-- region Main text --> + <g + id="layer1" + style="display:inline"> + + <!-- Main O --> + <text + xml:space="preserve" + style="font-size:305.166px;font-family:'JetBrains Mono';-inkscape-font-specification:'JetBrains Mono';display:inline;fill:#000000;stroke:#0f1893;stroke-width:1.27407;stroke-dasharray:none;stroke-opacity:1" + x="58.169628" + y="315.91675" + id="text1"><tspan + id="tspan1" + x="58.169628" + y="315.91675" + style="stroke-width:1.27407"><tspan + style="font-size:305.166px;fill:#0f1893;fill-opacity:1;stroke:#0f1893;stroke-width:1.27407;stroke-dasharray:none;stroke-opacity:1" + id="tspan2">O</tspan><tspan + style="font-size:305.166px;fill:#0980f3;fill-opacity:1;stroke:#0f1893;stroke-width:1.27407;stroke-opacity:1" + id="tspan3"/></tspan></text> + + <!-- Main S --> + <text + xml:space="preserve" + style="font-size:305.166px;font-family:'JetBrains Mono';-inkscape-font-specification:'JetBrains Mono';display:inline;fill:url(#linearGradient14);stroke-width:1.27407;stroke-dasharray:none" + x="164.80923" + y="315.91705" + id="text1-2"><tspan + id="tspan1-9" + x="164.80923" + y="315.91705" + style="fill:url(#linearGradient14);stroke-width:1.27407"><tspan + style="font-size:305.166px;fill:url(#linearGradient14);fill-opacity:1;stroke-width:1.27407" + id="tspan3-9">S</tspan></tspan></text> + </g> + <!-- endregion --> + <!-- region Mask --> + <g + id="layer2" + style="display:inline"> + <path + id="text1-5" + style="font-size:240px;font-family:'JetBrains Mono';-inkscape-font-specification:'JetBrains Mono';fill:#0f1893;fill-opacity:1;stroke-width:1.27407;stroke-dasharray:none" + d="m 112.15281,199.26602 c -2.23925,0.0681 -4.47848,0.14488 -6.7177,0.2111 -6.913168,0.20558 -13.830535,0.37614 -20.746668,0.57119 v 51.99579 c 0,21.56491 5.797795,38.14709 17.394018,49.74331 11.59622,11.59622 27.36473,17.39402 47.30208,17.39402 19.93735,0 35.70338,-5.7978 47.29961,-17.39402 11.59622,-11.59622 17.39401,-28.1784 17.39401,-49.74331 v -45.25325 c -2.75802,0.18397 -5.52806,0.24679 -8.28724,0.25083 -6.40343,-0.0823 -12.79486,-0.37984 -19.17712,-0.82698 v 48.88155 c 0,12.61344 -3.25475,22.38011 -9.76489,29.29714 -6.30675,6.71363 -15.46126,10.07034 -27.46437,10.07034 -11.79967,0 -20.95671,-3.35671 -27.46685,-10.07034 -6.51019,-6.91703 -9.76488,-16.6837 -9.76488,-29.29714 z"/> + </g> + <!-- endregion --> +</svg> diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index a8c5edb5..da9930a6 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -36,5 +36,7 @@ theme: icon: edit: material/pencil view: material/eye + logo: assets/logo.svg + favicon: assets/logo.svg edit_uri: edit/main/docs/website/docs -- 2.51.2 From e39f9a578bf8ffef3137f794109be7190d0faee5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:21:39 +0200 Subject: [PATCH 06/10] docs(website): Enable line selection for code samples --- docs/website/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index da9930a6..33ee70ca 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -11,7 +11,7 @@ theme: - content.action.view - content.code.annotate - content.code.copy - # - content.code.select + - content.code.select # - content.footnote.tooltips # - content.tabs.link - content.tooltips -- 2.51.2 From d812bb787d527f75b2b8463a637144d49870a1ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:26:47 +0200 Subject: [PATCH 07/10] docs(website): Let the user select between light and dark themes --- docs/website/mkdocs.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 33ee70ca..67b89add 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -38,5 +38,20 @@ theme: view: material/eye logo: assets/logo.svg favicon: assets/logo.svg + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: "System theme (click to switch to light)" + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: "Light theme (click to switch to dark)" + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: "Dark theme (click to switch to system)" edit_uri: edit/main/docs/website/docs -- 2.51.2 From 47d143b15514b7b95d7e1769b9e2c7df80210fbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:35:18 +0200 Subject: [PATCH 08/10] docs(website): Use the OpenSavvy color palette (approximately) --- docs/website/mkdocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 67b89add..77bcc3df 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -45,11 +45,15 @@ theme: name: "System theme (click to switch to light)" - media: "(prefers-color-scheme: light)" scheme: default + primary: deep purple + accent: cyan toggle: icon: material/brightness-7 name: "Light theme (click to switch to dark)" - media: "(prefers-color-scheme: dark)" scheme: slate + primary: deep purple + accent: cyan toggle: icon: material/brightness-4 name: "Dark theme (click to switch to system)" -- 2.51.2 From bed23ddca0ec5bf8794439cf511bc21cfa695817 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:37:27 +0200 Subject: [PATCH 09/10] docs(website): Create the main tabs --- docs/website/mkdocs.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 77bcc3df..98813dde 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -59,3 +59,12 @@ theme: name: "Dark theme (click to switch to system)" edit_uri: edit/main/docs/website/docs + +nav: + - Home: index.md + + - Getting started: [] + + - Module1: [] + + - Module2: [] -- 2.51.2 From 2c62272aae410cc693c0cc4f931a239673dace8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 21:48:35 +0200 Subject: [PATCH 10/10] docs(website): Custom home page --- docs/website/docs/index.md | 6 +++- docs/website/mkdocs.yml | 1 + docs/website/overrides/home.html | 61 ++++++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/website/overrides/home.html diff --git a/docs/website/docs/index.md b/docs/website/docs/index.md index ceea72a9..4f5ca0b6 100644 --- a/docs/website/docs/index.md +++ b/docs/website/docs/index.md @@ -1,3 +1,7 @@ -# Home +--- +template: home.html +--- + +# Welcome! The OpenSavvy Playground is a project template with pre-configured CI/CD, documentation generator, etc. diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 98813dde..112d0f9c 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -5,6 +5,7 @@ site_description: > theme: name: material + custom_dir: overrides features: - announce.dismiss - content.action.edit diff --git a/docs/website/overrides/home.html b/docs/website/overrides/home.html new file mode 100644 index 00000000..29eaa5eb --- /dev/null +++ b/docs/website/overrides/home.html @@ -0,0 +1,61 @@ +{% extends "main.html" %} +{% block tabs %} +{{ super() }} +<style> + #hero-page { + height: 100vh; + margin-left: 1rem; + margin-right: 1rem; + } + + #hero-title { + font-size: 3.7rem; + margin-top: 30vh; + margin-bottom: 1rem; + font-weight: bolder; + } + + @media screen and (min-width: 60em) { + .md-sidebar--secondary { + display: none + } + } + + @media screen and (min-width: 76.25em) { + .md-sidebar--primary { + display: none + } + } +</style> + +<section id="hero-page" class="mdx-container"> + <div class="md-typeset"> + <div class="mdx-hero"> + <div class="mdx-hero__content"> + <h1 id="hero-title">{{ config.site_name }}</h1> + + <p>{{ config.site_description }}</p> + + <div> <!-- Badges --> + + <a href="https://discord.gg/48Wv6BkJx6"><img src="https://img.shields.io/badge/Discuss-Discord-7289da"></a> + </div> + + <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | e }}" + class="md-button md-button--primary"> + Quick start + </a> + <a href="{{ config.repo_url }}" title="Material for MkDocs Insiders" class="md-button"> + Visit repository + </a> + </div> + </div> + </div> +</section> +{% endblock %} + +{% block content %} +<div style="min-height: 50vh"> + {{ super() }} +</div> +{% endblock %}