ADR-0000 - Choosing a programming Language and Framework for BFFH

docs/decisions/0000-Programming-language-and-framework-choice.md

@@ -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#)

docs/decisions/index.md

@@ -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/>.

docs/decisions/template.md

@@ -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 -->