From 23c3d7b433460fac4ee3ad3ed02ce7a544c7d928 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Wed, 10 Jan 2024 21:18:09 +0700 Subject: [PATCH] feat(adr): Add ADRs for Languages and Rust (#149) * docs(docs): Bump mkdocs and dependent library versions to current latest * fix(docs): update lock file * docs(ADR): Add ADR's for Language/Spelling and Rust * docs(mdlint): Fix line length issue * fix(docs): Rust ADRs are draft, and fix spelling --- Earthfile | 8 +- docs/mkdocs.yml | 2 + .../09_architecture_decisions/0001-draft.md | 35 -------- .../0002-proposed.md | 35 -------- .../0003-accepted.md | 35 -------- .../0003-language.md | 38 ++++++++ .../0004-rejected.md | 37 -------- .../0004-spelling.md | 53 +++++++++++ .../09_architecture_decisions/0005-rust.md | 87 +++++++++++++++++++ .../0005-superseded.md | 36 -------- .../0006-rust-cargo-lock.md | 47 ++++++++++ .../09_architecture_decisions/0006-test.md | 35 -------- .../0007-accepted.md | 38 -------- .../09_architecture_decisions/0008-all.md | 40 --------- 14 files changed, 234 insertions(+), 292 deletions(-) delete mode 100644 docs/src/architecture/09_architecture_decisions/0001-draft.md delete mode 100644 docs/src/architecture/09_architecture_decisions/0002-proposed.md delete mode 100644 docs/src/architecture/09_architecture_decisions/0003-accepted.md create mode 100644 docs/src/architecture/09_architecture_decisions/0003-language.md delete mode 100644 docs/src/architecture/09_architecture_decisions/0004-rejected.md create mode 100644 docs/src/architecture/09_architecture_decisions/0004-spelling.md create mode 100644 docs/src/architecture/09_architecture_decisions/0005-rust.md delete mode 100644 docs/src/architecture/09_architecture_decisions/0005-superseded.md create mode 100644 docs/src/architecture/09_architecture_decisions/0006-rust-cargo-lock.md delete mode 100644 docs/src/architecture/09_architecture_decisions/0006-test.md delete mode 100644 docs/src/architecture/09_architecture_decisions/0007-accepted.md delete mode 100644 docs/src/architecture/09_architecture_decisions/0008-all.md diff --git a/Earthfile b/Earthfile index 058fd27a5..070b9a50f 100644 --- a/Earthfile +++ b/Earthfile @@ -42,4 +42,10 @@ repo-config: WORKDIR /repo COPY --dir .sqlfluff . - SAVE ARTIFACT /repo repo \ No newline at end of file + SAVE ARTIFACT /repo repo + +# edit-docs - Target to assist in editing docs. +edit-docs: + LOCALLY + + RUN ./earthly/docs/dev/local.py cat-ci-docs:latest \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 8003a02f3..131abd234 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -35,6 +35,7 @@ extra: Kubernetes: kubernetes arc42: arc42 ADR: adr + Spelling: spell # Icons associated with the tags theme: @@ -55,3 +56,4 @@ theme: kubernetes: simple/kubernetes arc42: material/pencil-ruler adr: material/arrow-decision-auto + spell: fontawesome/solid/spell-check diff --git a/docs/src/architecture/09_architecture_decisions/0001-draft.md b/docs/src/architecture/09_architecture_decisions/0001-draft.md deleted file mode 100644 index ddc5ca1fd..000000000 --- a/docs/src/architecture/09_architecture_decisions/0001-draft.md +++ /dev/null @@ -1,35 +0,0 @@ ---- - title: 0001 draft - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: draft - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. diff --git a/docs/src/architecture/09_architecture_decisions/0002-proposed.md b/docs/src/architecture/09_architecture_decisions/0002-proposed.md deleted file mode 100644 index 7d8f670a7..000000000 --- a/docs/src/architecture/09_architecture_decisions/0002-proposed.md +++ /dev/null @@ -1,35 +0,0 @@ ---- - title: 0002 proposed - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: proposed - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. diff --git a/docs/src/architecture/09_architecture_decisions/0003-accepted.md b/docs/src/architecture/09_architecture_decisions/0003-accepted.md deleted file mode 100644 index 7569d8b3c..000000000 --- a/docs/src/architecture/09_architecture_decisions/0003-accepted.md +++ /dev/null @@ -1,35 +0,0 @@ ---- - title: 0003 accepted - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: accepted - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. diff --git a/docs/src/architecture/09_architecture_decisions/0003-language.md b/docs/src/architecture/09_architecture_decisions/0003-language.md new file mode 100644 index 000000000..84b0f2473 --- /dev/null +++ b/docs/src/architecture/09_architecture_decisions/0003-language.md @@ -0,0 +1,38 @@ +--- + title: 0003 Language + adr: + author: Steven Johnson + created: 09-Jan-2024 + status: accepted + tags: + - Spelling +--- + +## Context + +Any project contains a large amount of human readable text. +The team is multi-national and a common primary language needs to be chosen for the project. + +## Assumptions + +That everyone on the team will have a reasonable grasp of the primary language of the project. +That it will be reasonable to enforce the primary language on all team members contributions. + +## Decision + +After consultation with the existing team, +and considerations of the audience for the project the primary language of the project will be: + +* US English + +## Risks + +* That people where English is not a primary language will have difficulty conforming to the requirement. + +## Consequences + +Having a uniform language for the project makes it easier for people to interact on a common basis. + +## More Information + +* [Why English is the Lingua Franca of Programming](https://ystudios.com/insights-passion/codelanguage) diff --git a/docs/src/architecture/09_architecture_decisions/0004-rejected.md b/docs/src/architecture/09_architecture_decisions/0004-rejected.md deleted file mode 100644 index d5b3cb68a..000000000 --- a/docs/src/architecture/09_architecture_decisions/0004-rejected.md +++ /dev/null @@ -1,37 +0,0 @@ ---- - title: 0004 rejected - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: rejected - extends: - - 0008-all - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. diff --git a/docs/src/architecture/09_architecture_decisions/0004-spelling.md b/docs/src/architecture/09_architecture_decisions/0004-spelling.md new file mode 100644 index 000000000..258553075 --- /dev/null +++ b/docs/src/architecture/09_architecture_decisions/0004-spelling.md @@ -0,0 +1,53 @@ +--- + title: 0004 Spelling + adr: + author: Steven Johnson + created: 09-Jan-2024 + status: accepted + extends: + - 0003-language + tags: + - Spelling +--- + +## Context + +Any project contains a large amount of human readable text. +The team is multi-national and it can not be assumed that everyone has a strong +skills with the primary language of the project. + +## Assumptions + +That everyone on the team has a reasonable grasp of the primary language of the project. + +## Decision + +That the spelling of the Primary Language will be enforced in CI using: + +* [CSpell] +* US English dictionaries +* Technical words +* Custom words on a pre-project basis + +Secondary Languages which are used in translating the UI, will also be checked with [CSpell]. + +## Risks + +* That a dictionary for a Secondary language does not exist for CSpell. + +It is possible to use custom dictionaries with [CSpell]. +If a standard dictionary does not exist, a custom language dictionary can be added. +This risk is mitigated. + +## Consequences + +Enforcing spelling in CI helps enforce consistency of all Human Readable text. +By using automation we ensure this consistency, regardless of a contributors proficiency with the primary language + +`cspell` + +## More Information + +* [CSpell] + +[CSpell]: http://cspell.org/ diff --git a/docs/src/architecture/09_architecture_decisions/0005-rust.md b/docs/src/architecture/09_architecture_decisions/0005-rust.md new file mode 100644 index 000000000..a1a443f6a --- /dev/null +++ b/docs/src/architecture/09_architecture_decisions/0005-rust.md @@ -0,0 +1,87 @@ +--- + title: 0005 Rust + adr: + author: Steven Johnson + created: 09-Jan-2024 + status: draft + tags: + - Rust +--- + +## Context + +Languages used in the project need to be chosen based on: + +* their strengths +* suitability to the tasks they are used for +* familiarity with the team. + +## Assumptions + +* That the language chosen will continue to be a mainstream language. +* That it will be reasonably easy to find developers proficient in it. + +## Decision + +Backend and System level services can be coded in: + +* Rust + +Other languages can be also be used for these services as described by their own ADR. + +## Risks + +1. Learning Curve: Rust has a steep learning curve, especially for developers + who are new to systems programming or low-level languages. + The language enforces strict memory safety rules and introduces concepts + like ownership, borrowing, and lifetimes, which can be challenging to grasp initially. + This learning curve may require additional time and effort for developers to become proficient in Rust. +2. Ecosystem Immaturity: While Rust has a growing ecosystem, + it may not have the same level of maturity and breadth as more established languages. + This can result in a smaller selection of libraries and tools compared to languages like Python or Java. + However, the Rust community actively develops and maintains high-quality libraries, and many common use cases are well-supported. +3. Development Speed: Rust's focus on safety and strict compile-time checks can sometimes slow down development speed, + especially for rapid prototyping or small-scale projects. + The compile times in Rust can be longer compared to other languages, which may impact the iterative development process. + However, the benefits of safety and performance often outweigh this trade-off in larger-scale projects. + +Despite these risks, Rust's benefits in terms of memory safety, performance, and concurrency +make it a compelling choice for backend systems programming. + +## Consequences + +1. Memory Safety: Rust's ownership system and borrow checker ensure memory safety at compile time, + preventing common bugs like null pointer dereferences, buffer overflows, and data races. +2. Performance: Rust enables low-level control over resources, developers can write efficient code with minimal runtime overhead. + It offers zero-cost abstractions and fine-grained control over memory allocation. +3. Concurrency: Rust's ownership model and built-in concurrency primitives, + such as threads and channels, make it easy to write safe and concurrent code. + The async/await syntax and the tokio library provide powerful asynchronous programming capabilities. +4. Safety Guarantees: Rust's strict compile-time checks enforce safe programming practices, + eliminating undefined behavior and making code more reliable. + The language prevents common programming mistakes by catching them at compile time. +5. Developer Experience: Rust has a growing ecosystem of libraries and tools, + making it easier to build robust applications. + The language promotes clear and explicit code, + with helpful error messages and a strong type system that aids in code maintainability. +6. Cross-platform Support: Rust is designed to be portable and can target a wide range of platforms, + including desktop, mobile, and embedded systems. + It supports various architectures and operating systems, making it versatile for different use cases. +7. Interoperability: Rust can seamlessly interface with other languages, + allowing developers to leverage existing code-bases or libraries. + It provides C-compatible FFI (Foreign Function Interface) and supports integration with languages like C, C++, and Python. +8. Community: Rust has a vibrant and supportive community that actively contributes to the language's development + and provides valuable resources, documentation, and libraries. + The community fosters a culture of knowledge sharing and collaboration. +9. Tooling: Rust has a powerful package manager called Cargo, which simplifies dependency management and project build processes. + It also offers excellent IDE support, code formatting, and extensive testing frameworks. +10. Future-proofing: Rust is designed for long-term stability and compatibility. + The language emphasizes backward compatibility and provides a strong commitment to avoiding breaking changes. + This ensures that code written in Rust today will continue to work in the future. + +## More Information + +* [Rust](https://www.rust-lang.org/) +* [Rust: A Language for the Next 40 Years](https://youtu.be/A3AdN7U24iU?si=NO__XP8DPZuRKBUB) - This video presentation by + Carol Nichols highlights Rust's strengths and discusses its unique features, + including memory safety, zero-cost abstractions, and concurrency. diff --git a/docs/src/architecture/09_architecture_decisions/0005-superseded.md b/docs/src/architecture/09_architecture_decisions/0005-superseded.md deleted file mode 100644 index 03288930f..000000000 --- a/docs/src/architecture/09_architecture_decisions/0005-superseded.md +++ /dev/null @@ -1,36 +0,0 @@ ---- - title: 0005 superseded - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: superseded - superseded_by: 0006-test - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. diff --git a/docs/src/architecture/09_architecture_decisions/0006-rust-cargo-lock.md b/docs/src/architecture/09_architecture_decisions/0006-rust-cargo-lock.md new file mode 100644 index 000000000..3a5628c37 --- /dev/null +++ b/docs/src/architecture/09_architecture_decisions/0006-rust-cargo-lock.md @@ -0,0 +1,47 @@ +--- + title: 0006 Rust Cargo Lock + adr: + author: Steven Johnson + created: 09-Jan-2024 + status: draft + extends: + - 0005-rust + tags: + - Rust +--- + +## Context + +Rust has an optional `cargo.lock` file which can lock the dependencies of a project. +There are [pros and cons][Cargo/toml vs Cargo.lock] to using the `lock` file. + +## Assumptions + +This ADR is deliberately limited to the initial bring up phase of our projects, and subject to review. + +## Decision + +Rust will [not][Why have Cargo.lock in Version Control] use `cargo.lock` when consuming libraries. +It will ONLY respect it for building binaries. + +As we are in the initial stages of a number of projects, it is easier to iterate without +worrying about `cargo.lock` being up-to-date. + +Accordingly, until the binaries we would publish approach releasable state we will not +use the `cargo.lock` file. + +## Risks + +We forget to introduce `cargo.lock` on our binaries when we approach release. + +## Consequences + +This should make it a little easier to iterate with less issues caused by out of date `cargo.lock` files finding there way into CI. + +## More Information + +* [Cargo/toml vs Cargo.lock] +* [Why have Cargo.lock in Version Control] + +[Cargo/toml vs Cargo.lock]: https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html +[Why have Cargo.lock in Version Control]: https://doc.rust-lang.org/cargo/faq.html#why-have-cargolock-in-version-control diff --git a/docs/src/architecture/09_architecture_decisions/0006-test.md b/docs/src/architecture/09_architecture_decisions/0006-test.md deleted file mode 100644 index cfa2c0bcf..000000000 --- a/docs/src/architecture/09_architecture_decisions/0006-test.md +++ /dev/null @@ -1,35 +0,0 @@ ---- - title: 0006 test - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: accepted - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. diff --git a/docs/src/architecture/09_architecture_decisions/0007-accepted.md b/docs/src/architecture/09_architecture_decisions/0007-accepted.md deleted file mode 100644 index 2e0d3fae6..000000000 --- a/docs/src/architecture/09_architecture_decisions/0007-accepted.md +++ /dev/null @@ -1,38 +0,0 @@ ---- - title: 0007 accepted - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: accepted - extends: - - 0003-accepted - - 0002-proposed - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well. diff --git a/docs/src/architecture/09_architecture_decisions/0008-all.md b/docs/src/architecture/09_architecture_decisions/0008-all.md deleted file mode 100644 index dee5e00e6..000000000 --- a/docs/src/architecture/09_architecture_decisions/0008-all.md +++ /dev/null @@ -1,40 +0,0 @@ ---- - title: 0008 all - adr: - author: Steven Johnson - created: 01-Aug-2023 - status: superseded - superseded_by: 0007-accepted - extends: - - 0001-draft - - 0002-proposed - - 0003-accepted - tags: - - tag2 - - tag3 ---- - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Assumptions - -Anything that could cause problems if untrue now or later - -## Decision - -What is the change that we're proposing and/or doing? - -## Risks - -Anything that could cause malfunction, delay, or other negative impacts - -## Consequences - -What becomes easier or more difficult to do because of this change? - -## More Information - -Provide additional evidence/confidence for the decision outcome -Links to other decisions and resources might here appear as well.