diff --git a/docs/decisions/0000-Programming-language-and-framework-choice.md b/docs/decisions/0000-Programming-language-and-framework-choice.md new file mode 100644 index 0000000..3569c27 --- /dev/null +++ b/docs/decisions/0000-Programming-language-and-framework-choice.md @@ -0,0 +1,111 @@ +# Choosing a programming Language and Framework for BFFH + +* Status: accepted +* Date: 18.02.2020 (?) + +Technical Story: Decision regarding programming language and framework to use in BFFH / the backend code of FabAccess + +## 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 + +* 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 + +* 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 + +* 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 + +### 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 + +* 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#) diff --git a/docs/decisions/index.md b/docs/decisions/index.md new file mode 100644 index 0000000..132ae19 --- /dev/null +++ b/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). + + + +* [ADR-0000](0000-Programming-language-and-framework-choice.md) - Choosing a programming Language and Framework for BFFH + + + +For new ADRs, please use [template.md](template.md) as basis. +More information on MADR is available at . +General information about architectural decision records is available at . diff --git a/docs/decisions/template.md b/docs/decisions/template.md new file mode 100644 index 0000000..25696bb --- /dev/null +++ b/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)] +* Deciders: [list everyone involved in the decision] +* Date: [YYYY-MM-DD when the decision was last updated] + +Technical Story: [description | ticket/issue URL] + +## 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 + +* [driver 1, e.g., a force, facing concern, …] +* [driver 2, e.g., a force, facing concern, …] +* … + +## Considered Options + +* [option 1] +* [option 2] +* [option 3] +* … + +## 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 + +* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] +* … + +### Negative Consequences + +* [e.g., compromising quality attribute, follow-up decisions required, …] +* … + +## Pros and Cons of the Options + +### [option 1] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +### [option 2] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +### [option 3] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +## Links + +* [Link type] [Link to ADR] +* …