From a1d29489142957696f8c33aaa6e187b80240d6d3 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 14 May 2025 10:06:24 +0200 Subject: [PATCH] docs(adrs): move decision folder into docs to make them publicly visible within docs --- decisions/README.md | 1 - docs/mkdocs.yml | 12 +++++++++++- .../site/decisions}/01-ClanModules.md | 15 ++++++++------- .../site/decisions}/02-clan-api.md | 6 ++---- .../site/decisions}/03-adr-numbering-process.md | 0 docs/site/decisions/README.md | 16 ++++++++++++++++ {decisions => docs/site/decisions}/_template.md | 0 7 files changed, 37 insertions(+), 13 deletions(-) delete mode 100644 decisions/README.md rename {decisions => docs/site/decisions}/01-ClanModules.md (99%) rename {decisions => docs/site/decisions}/02-clan-api.md (95%) rename {decisions => docs/site/decisions}/03-adr-numbering-process.md (100%) create mode 100644 docs/site/decisions/README.md rename {decisions => docs/site/decisions}/_template.md (100%) diff --git a/decisions/README.md b/decisions/README.md deleted file mode 100644 index 68ef5a443..000000000 --- a/decisions/README.md +++ /dev/null @@ -1 +0,0 @@ -see [architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b79b0c549..8407c4977 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -22,7 +22,11 @@ markdown_extensions: emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.tasklist: custom_checkbox: true - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - pymdownx.details @@ -75,6 +79,12 @@ nav: - Migrate inventory Services: guides/migrate-inventory-services.md - Reference: - Overview: reference/index.md + - Architecture Decisions: + - Architecture Decisions: decisions/README.md + - 01-clanModules: decisions/01-ClanModules.md + - 02-clan-api: decisions/02-clan-api.md + - 03-adr-numbering-process: decisions/03-adr-numbering-process.md + - Template: decisions/_template.md - Clan Modules: - Overview: - reference/clanModules/index.md diff --git a/decisions/01-ClanModules.md b/docs/site/decisions/01-ClanModules.md similarity index 99% rename from decisions/01-ClanModules.md rename to docs/site/decisions/01-ClanModules.md index 57bc79880..cba6ddcf2 100644 --- a/decisions/01-ClanModules.md +++ b/docs/site/decisions/01-ClanModules.md @@ -1,6 +1,8 @@ # Clan service modules -Status: Accepted +## Status + +Accepted ## Context @@ -65,9 +67,9 @@ Problems with the current way of writing clanModules: 1. No way to retrieve the config of a single service instance, together with its name. 2. Directly exporting a single, anonymous nixosModule without any intermediary attribute layers doesn't leave room for exporting other inventory resources such as potentially `vars` or `homeManagerConfig`. 3. Can't access multiple config instances individually. - Example: - ```nix - inventory = { + Example: + ```nix + inventory = { services = { network.c-base = { instanceConfig.ips = { @@ -81,7 +83,7 @@ Problems with the current way of writing clanModules: }; }; }; - ``` + ``` This doesn't work because all instance configs are applied to the same namespace. So this results in a conflict currently. Resolving this problem means that new inventory modules cannot be plain nixos modules anymore. If they are configured via `instances` / `instanceConfig` they cannot be configured without using the inventory. (There might be ways to inject instanceConfig but that requires knowledge of inventory internals) @@ -256,7 +258,6 @@ The following thoughts went into this: We want to implement the system as described. Once we have sufficient data on real world use-cases and modules we might revisit this document along with the updated implementation. - ## Real world example The following module demonstrates the idea in the example of *borgbackup*. @@ -407,7 +408,7 @@ The following module demonstrates the idea in the example of *borgbackup*. '' ) (lib.attrValues config.clan.core.state)} - if [[ ''${#preCommandErrors[@]} -gt 0 ]]; then + if [[ ''${preCommandErrors[@]} -gt 0 ]]; then echo "pre-backup commands failed for the following services:" for state in "''${!preCommandErrors[@]}"; do echo " $state" diff --git a/decisions/02-clan-api.md b/docs/site/decisions/02-clan-api.md similarity index 95% rename from decisions/02-clan-api.md rename to docs/site/decisions/02-clan-api.md index 108d14505..a51730e91 100644 --- a/decisions/02-clan-api.md +++ b/docs/site/decisions/02-clan-api.md @@ -22,11 +22,9 @@ This leads to the conclusion that we should do `library` centric development. With the current `clan` python code being a library that can be imported to create various tools ontop of it. All **CLI** or **UI** related parts should be moved out of the main library. -*Note: The next person who wants implement any new frontend should do this first. Currently it looks like the TUI is the next one.* - Imagine roughly the following architecture: -```mermaid +``` mermaid graph TD %% Define styles classDef frontend fill:#f9f,stroke:#333,stroke-width:2px; @@ -75,7 +73,7 @@ Integration tests and smaller unit-tests should both be utilized to ensure the s Note: Library function don't have to be json-serializable in general. -Persistence includes but is not limited to: creating git commits, writing to inventory.json, reading and writing vars and to/from disk in general. +Persistence includes but is not limited to: creating git commits, writing to inventory.json, reading and writing vars, and interacting with persisted data in general. ## Benefits / Drawbacks diff --git a/decisions/03-adr-numbering-process.md b/docs/site/decisions/03-adr-numbering-process.md similarity index 100% rename from decisions/03-adr-numbering-process.md rename to docs/site/decisions/03-adr-numbering-process.md diff --git a/docs/site/decisions/README.md b/docs/site/decisions/README.md new file mode 100644 index 000000000..e6839a4ac --- /dev/null +++ b/docs/site/decisions/README.md @@ -0,0 +1,16 @@ +# Architecture Decision Records + +This section contains the architecture decisions that have been reviewed and generally agreed upon + +## What is an ADR? + +> An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences. + +!!! Note + For further reading about adr's we recommend [architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record) + +## Crafting a new ADR + +1. Use the [template](./_template.md) +2. Create the Pull request and gather feedback +3. Retreive your adr-number (see: [numbering](./03-adr-numbering-process.md)) diff --git a/decisions/_template.md b/docs/site/decisions/_template.md similarity index 100% rename from decisions/_template.md rename to docs/site/decisions/_template.md