vmario/fabaccess-bffh
1
0
Fork 0
mirror of https://gitlab.com/fabinfra/fabaccess/bffh.git synced 2024-12-22 03:33:48 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feature/adr-backfill' into 'development'

Browse Source 
Draft: ADR backfill

Closes #42

See merge request fabinfra/fabaccess/bffh!26
This commit is contained in:
Nadja von Reitzenstein Čerpnjak 2024-12-14 21:04:12 +00:00
commit cd644ea853
3 changed files with 197 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
docs/decisions/0000-Programming-language-and-framework-choice.md Normal file
View File

@ -0,0 +1,111 @@
# Choosing a programming Language and Framework for BFFH
* Status: accepted <!-- optional -->
* Date: 18.02.2020 (?) <!-- optional -->
Technical Story: Decision regarding programming language and framework to use in BFFH / the backend code of FabAccess <!-- optional -->
## Context and Problem Statement
Programming language Dicussions are the perfect [bikeshedding](http://catb.org/jargon/html/B/bikeshedding.html) topic.
Regardless at some point a decision has to be made so that people can start writing code and being generally useful.
Since FabAccess started as a project with several potential developers and even more stakeholders interested/relying on
the success of the software this discussion was *extra* spicy.
The relevant discussions were had in the timeframe from about November of 2019 to March of 2020.
## Decision Drivers <!-- optional -->
* Available developers, both short-term and medium-term should the project become a successful staple of
german/european/terran makerspaces
* Barrier of entry for new / additional developers.
* Tooling support, esp. regarding non-developers (documentation, ease of self-compilation, …)
* Library support / ecosystem in the problem domain
* Existing projects that could be extended as to not invent the wheel again
* Language Features
## Considered Options
* Python
* TypeScript
* Rust
* Erlang
* Ruby
* Haskell
## Decision Outcome
Chosen option: "Rust", because the project ended up mostly being developed by FabInfra whos cost/benefit analisys skews
in favour of type safety over speed of development.
### Positive Consequences <!-- optional -->
* Type safety of Rust strong compared to all other options barring Haskell
* Single statically linked binary with very few dependencies makes deployment trivial
* Compiled software close to the metal allows running the server on low-powered hardware such as Raspberry Pis even for
medium-sized deployments.
### Negative Consequences <!-- optional -->
* Speed of development suffers short-term. Rust is a lower-level language than all other evaluated options and requires
more thought and developer time to implement high level features.
* Available developer pool is small and expensive. Rust is not a good first programming language and comparatively hard
to get into for developers if they don't have experience with C++. Developers are available to hire but salary
expectation of Rust developers is high compared to Python / Java.
* Small ecosystem / few libraries. Rust is a very young programming language and despite being rated as the most popular
language on SO for several years and being commercially used has fewer libraries than most other options. Support for
e.g. LDAP is not mature. But problem domain of FabAccess is in the area that Rust has the most support for.
## Pros and Cons of the Options <!-- optional -->
### Python
* Good, because large available developer pool
* Good, because of the developers interested in developing it large parts have experience with Python
* Good, because Python is easy to learn and a good first language
* Good, because Python has extensive library support and an ecosystem geared towards automation
* Bad, because comparatively slow. Slowest or second slowest option considered.
* Bad, because highly dynamic typing and mediocre static analysis has potential for edgecase bugs being hidden for long
times
* Bad, because Python gives little control over the crash process. Catching exceptions is very coarse.
### TypeScript
* Good, because stronger typing than Python and Ruby
* Bad, because interpreted language and while faster than Ruby/Python still much slower than the compiled options.
* Bad, because the Node.js ecosystem is large but not all that much geared towards low level automation
### Rust
* Good, because Rust has a good type system allowing to prevent many bugs and crashes using static analysis built
into the compiler.
* Good, because Rust code is very efficient.
* Good, because many people are very interested in learning Rust and are only lacking a reason to.
* Bad, because speed of development is slower than for most other options.
* Bad, because only one developer in the group has any experience with Rust.
* Bad, because available developer pool is small.
### Erlang
* Good, because specifically built for highly-available, crash-resistant software
* Good, because it offers an extremely fine-grained crashing system with encapsulated processes that can not take each
other down
* Good, because the ecosystem and libraries of Erlang are generally geared towards the problem domain of FabAccess
* Good, because Erlang allows for significant static analysis compared to TypeScript, Pyton and Ruby
* Bad, because Erlang has a worse type system than Rust and Haskell.
* Bad, because only one developer in the group has any experience with Erlang.
* Bad, because the developer pool is the second smallest.
### Haskell
* Good, because strongest type system allowing to prevent many bugs and crashes using static analysis built into the
compiler
* Bad, because only one developer has any experience with Haskell.
* Bad, because the developer pool is the smallest.
## Links <!-- optional -->
* Discussions documented in:
- [Protokoll Jit.si-Konferenz 09.12.19](https://pad.gwdg.de/obbgQwKiQNmRRwDt1yERew?view#Kuratiertes-Framework-vs-Erweiterbarer-Monolith)
- [Pad "Roseguarden"](https://pad.gwdg.de/v-xVnpWQREmBGuLG_hYTfQ#Projektinterne-Werkzeuge)
- [Pad BF²H "Grundlegendes"](https://pad.gwdg.de/XrReiGdCS-GfcWhEKgjTBA#)
- [JitSi Call 18.02](https://pad.gwdg.de/71fd449SRgGm_HhL4rgVqw#)

14
docs/decisions/index.md Normal file
View File

@ -0,0 +1,14 @@
# Architectural Decision Log
This log lists the architectural decisions for Diflouroborane (BFFH).
See also the ADR log of [FabAccess-API](https://gitlab.com/fabinfra/fabaccess/fabaccess-api/-/tree/main/docs/decisions).
<!-- adrlog -- Regenerate the content by using "adr-log -i". You can install it via "npm install -g adr-log" -->
* [ADR-0000](0000-Programming-language-and-framework-choice.md) - Choosing a programming Language and Framework for BFFH
<!-- adrlogstop -->
For new ADRs, please use [template.md](template.md) as basis.
More information on MADR is available at <https://adr.github.io/madr/>.
General information about architectural decision records is available at <https://adr.github.io/>.

72
docs/decisions/template.md Normal file
View File

@ -0,0 +1,72 @@
# [short title of solved problem and solution]
* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
* Deciders: [list everyone involved in the decision] <!-- optional -->
* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
Technical Story: [description | ticket/issue URL] <!-- optional -->
## Context and Problem Statement
[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
## Decision Drivers <!-- optional -->
* [driver 1, e.g., a force, facing concern, …]
* [driver 2, e.g., a force, facing concern, …]
* … <!-- numbers of drivers can vary -->
## Considered Options
* [option 1]
* [option 2]
* [option 3]
* … <!-- numbers of options can vary -->
## Decision Outcome
Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
### Positive Consequences <!-- optional -->
* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
* …
### Negative Consequences <!-- optional -->
* [e.g., compromising quality attribute, follow-up decisions required, …]
* …
## Pros and Cons of the Options <!-- optional -->
### [option 1]
[example | description | pointer to more information | …] <!-- optional -->
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->
### [option 2]
[example | description | pointer to more information | …] <!-- optional -->
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->
### [option 3]
[example | description | pointer to more information | …] <!-- optional -->
* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->
## Links <!-- optional -->
* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
* … <!-- numbers of links can vary -->