Adds a ADR on the motivation of the decision

Keysight · May 2, 2022 · 16a4611 · 16a4611
1 parent e830f82
commit 16a4611
Show file tree

Hide file tree

Showing 4 changed files with 186 additions and 0 deletions.
diff --git a/dev_docs/decisions/0000-use-markdown-architectural-decision-records.md b/dev_docs/decisions/0000-use-markdown-architectural-decision-records.md
@@ -0,0 +1,28 @@
+# Use Markdown Architectural Decision Records
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 2.1.2 – The Markdown Architectural Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+* Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 2.1.2", because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.
+* Version 2.1.2 is the latest one available when starting to document ADRs.
+
+<!-- markdownlint-disable-file MD013 -->
diff --git a/dev_docs/decisions/0001-change-cicd-pipeline-service-provider.md b/dev_docs/decisions/0001-change-cicd-pipeline-service-provider.md
@@ -0,0 +1,65 @@
+# Change CI/CD pipeline service provider
+
+* Status:
+    * [x] proposed
+    * [ ] rejected
+    * [ ] accepted
+    * [ ] deprecated
+    * [ ] superseded by ...
+
+## Context and Problem Statement
+
+We want to have a CI/CD pipeline that runs for PRs and to publish packages to PYPI. Previously we used Travis CI for
+this. This ADR proposes a change to a different provider.
+
+## Decision Drivers <!-- optional -->
+
+* Recently Travis had a security incident that potentially gave attackers access to secure assets. This is not the first
+  incident of that kind
+    * https://github.blog/2022-04-15-security-alert-stolen-oauth-user-tokens/
+    * https://www.theregister.com/2021/09/15/travis_ci_leak/
+* We were less and less happy with how to configure Travis CI
+* In general Travis fell a bit out of favor in the open source community since they layed off a large part of their
+  developer team
+
+## Considered Options
+
+* Github Actions
+* Travis CI (no change)
+* Gitlab
+
+## Decision Outcome
+
+Chosen option: "Github Actions", because
+
+- Good integration: we currently use Github already for hosting the code repo of this project.
+- actively developed, backed by big corporate $$$
+- Lots of tutorials/docs available
+- Very flexible (3rd party plugins are available to define actions)
+
+### Negative Consequences <!-- optional -->
+
+* We need to learn a new pipeline syntax.
+    * However so far only me and Siebe were working on Travis actions
+
+## Pros and Cons of the Options <!-- optional -->
+
+### Github Actions
+
+* Good, because well integrated with the github code repository which we use
+* Good, because actively maintained/developed
+* Bad, because learning new syntax is required
+
+### Travis CI
+
+* Good, because we know it
+* Bad, because subjectively too often in the news about security incidents
+* Bad, because not so actively developed anymore
+
+### Gitlab
+
+* Good, because all in one platform (code repo, project management, CI/CD, package repos)
+* Bad, because we do not want to switch code repos at the moment
+    * Yes there are ways to use a gitlab pipeline with a github repo, but why bother?
+
+<!-- markdownlint-disable-file MD013 -->
diff --git a/dev_docs/decisions/adr-template.md b/dev_docs/decisions/adr-template.md
@@ -0,0 +1,77 @@
+# {short title of solved problem and solution}
+
+* Status:
+  * [x] proposed
+  * [ ] rejected
+  * [ ] accepted
+  * [ ] deprecated
+  * [ ] superseded by ...
+
+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 -->
+
+<!-- markdownlint-disable-file MD013 -->
diff --git a/dev_docs/decisions/index.md b/dev_docs/decisions/index.md
@@ -0,0 +1,16 @@
+# Architectural Decision Log
+
+This log lists the architectural decisions for the trsfile python library.
+
+<!-- adrlog -- Regenerate the content by using "adr-log -i". You can install it via "npm install -g adr-log" -->
+
+- [ADR-0000](0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records
+- [ADR-0001](0001-change-cicd-pipeline-service-provider.md) - Change CI/CD pipeline service provider
+
+<!-- adrlogstop -->
+
+For new ADRs, please use [adr-template.md](adr-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/>.
+
+<!-- markdownlint-disable-file MD013 -->