From e3d84391b4242d6c9e3c986ffe956124e6f37de3 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Tue, 20 Oct 2020 22:50:00 +0100 Subject: [PATCH 1/4] docs/adr: start to keep ADRs in MADR format In order to make decisions about the code and the design explicit and easier to reference in future we want to record significant architectural decisions. This commit introduces docs/adr with a template Architectural Decision Record and index using the [MADR](https://adr.github.io/madr/) format. It also adds ADR 0000 to document the decisions to use MADR. Fixes #1141 Signed-off-by: Joshua Lock --- ...markdown-architectural-decision-records.md | 25 +++++++ docs/adr/index.md | 13 ++++ docs/adr/template.md | 72 +++++++++++++++++++ 3 files changed, 110 insertions(+) create mode 100644 docs/adr/0000-use-markdown-architectural-decision-records.md create mode 100644 docs/adr/index.md create mode 100644 docs/adr/template.md diff --git a/docs/adr/0000-use-markdown-architectural-decision-records.md b/docs/adr/0000-use-markdown-architectural-decision-records.md new file mode 100644 index 0000000000..44c4027b47 --- /dev/null +++ b/docs/adr/0000-use-markdown-architectural-decision-records.md @@ -0,0 +1,25 @@ +# Use Markdown Architectural Decision Records + +* Status: accepted +* Date: 2020-10-20 + +Technical Story: https://github.com/theupdateframework/tuf/issues/1141 + +## 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 +* 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. +* The MADR structure is comprehensible and facilitates usage & maintenance. diff --git a/docs/adr/index.md b/docs/adr/index.md new file mode 100644 index 0000000000..388b3950b3 --- /dev/null +++ b/docs/adr/index.md @@ -0,0 +1,13 @@ +# Architectural Decision Log + +This log lists the architectural decisions for tuf. + + + +- [ADR-0000](0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records + + + +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/adr/template.md b/docs/adr/template.md new file mode 100644 index 0000000000..25696bbe7c --- /dev/null +++ b/docs/adr/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] +* … From 19b93565986a43d12ea0d57f399d58f9d0b2099c Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Wed, 21 Oct 2020 10:47:01 +0100 Subject: [PATCH 2/4] Teach git to ignore Emacs backup files Signed-off-by: Joshua Lock --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 9e100761bc..11e270e193 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ env/* tests/htmlcov/* .DS_Store .python-version +*~ \ No newline at end of file From 71de3f64efe39c5de3011c4a86fe758d85def973 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Tue, 20 Oct 2020 22:51:57 +0100 Subject: [PATCH 3/4] ADR: only use Python 3.6+ Document the decision drop support for EOL Python versions, most notable Python 2.7 Fixes #1125 Signed-off-by: Joshua Lock --- docs/adr/0001-python-version-3-6-plus.md | 39 ++++++++++++++++++++++++ docs/adr/index.md | 1 + 2 files changed, 40 insertions(+) create mode 100644 docs/adr/0001-python-version-3-6-plus.md diff --git a/docs/adr/0001-python-version-3-6-plus.md b/docs/adr/0001-python-version-3-6-plus.md new file mode 100644 index 0000000000..e96a829bd6 --- /dev/null +++ b/docs/adr/0001-python-version-3-6-plus.md @@ -0,0 +1,39 @@ +# Default to Python 3.6 or newer for new development + +* Status: accepted +* Date: 2020-10-20 + +Technical Story: https://github.com/theupdateframework/tuf/issues/1125 + +## Context and Problem Statement + +We do not want to try and support end-of-life versions of the language. +We want to use modern language features, such as typing. +We want to ease maintainer burden, by reducing the major language versions supported. + +## Decision Drivers + +* Python 2.7 is end-of-life +* Python 3.5 is end-of-life +* Modern Python allows use of desirable features such as type hints +* Supporting end-of-life Python versions adds maintenance overhead + +## Considered Options + +* Support Python 2.7 and 3.5+ +* Support Python 2.7 and 3.6+ +* Support Python 2.7 and 3.6+ (with polyfill modules) +* Support only Python 3.6+ + +## Decision Outcome + +Chosen option: "Support only Python 3.6+", because we want modern features and lower +maintainer effort as we work to improve our codebase through the refactor effort. + +Using modules to polyfill standard library features from Python 3.6+ feels +untenable as more libraries are dropping support for EOL Python releases. + +### Negative Consequences + +* Leaves major adopter and contributor without an actively developed client for some of + their customers stuck on older Python versions. diff --git a/docs/adr/index.md b/docs/adr/index.md index 388b3950b3..b9c23b2a25 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -5,6 +5,7 @@ This log lists the architectural decisions for tuf. - [ADR-0000](0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records +- [ADR-0001](0001-python-version-3-6-plus.md) - Default to Python 3.6 or newer for new development From 1b3f580dc9ab61fe682fa7b14c4762ab4823b1c1 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Tue, 27 Oct 2020 11:25:40 +0000 Subject: [PATCH 4/4] ADR0001: clarify when/where Python 3.6+ is expected Provide additional context to clarify where we expect Python 3.6+ to be used exclusively (new modules) and link to other discussions around the future of Python 2.7 supporting code. Signed-off-by: Joshua Lock --- docs/adr/0001-python-version-3-6-plus.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/adr/0001-python-version-3-6-plus.md b/docs/adr/0001-python-version-3-6-plus.md index e96a829bd6..4ce8b54b8c 100644 --- a/docs/adr/0001-python-version-3-6-plus.md +++ b/docs/adr/0001-python-version-3-6-plus.md @@ -7,9 +7,11 @@ Technical Story: https://github.com/theupdateframework/tuf/issues/1125 ## Context and Problem Statement -We do not want to try and support end-of-life versions of the language. -We want to use modern language features, such as typing. -We want to ease maintainer burden, by reducing the major language versions supported. +We are planning a refactor of tuf where: + +* We do not want to try and support end-of-life versions of the language. +* We want to use modern language features, such as typing. +* We want to ease maintainer burden, by reducing the major language versions supported. ## Decision Drivers @@ -30,6 +32,8 @@ We want to ease maintainer burden, by reducing the major language versions suppo Chosen option: "Support only Python 3.6+", because we want modern features and lower maintainer effort as we work to improve our codebase through the refactor effort. +New modules should target Python 3.6+. + Using modules to polyfill standard library features from Python 3.6+ feels untenable as more libraries are dropping support for EOL Python releases. @@ -37,3 +41,8 @@ untenable as more libraries are dropping support for EOL Python releases. * Leaves major adopter and contributor without an actively developed client for some of their customers stuck on older Python versions. + +## Links + +* [Discussion of how/where to develop the refactored codebase](https://github.com/theupdateframework/tuf/issues/1126) +* [Discussion of deprecation policy for the pre-1.0, Python 2.7 supporting, code](https://github.com/theupdateframework/tuf/issues/1127)