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 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/0001-python-version-3-6-plus.md b/docs/adr/0001-python-version-3-6-plus.md new file mode 100644 index 0000000000..4ce8b54b8c --- /dev/null +++ b/docs/adr/0001-python-version-3-6-plus.md @@ -0,0 +1,48 @@ +# 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 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 + +* 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. + +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. + +### Negative Consequences + +* 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) diff --git a/docs/adr/index.md b/docs/adr/index.md new file mode 100644 index 0000000000..b9c23b2a25 --- /dev/null +++ b/docs/adr/index.md @@ -0,0 +1,14 @@ +# 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 +- [ADR-0001](0001-python-version-3-6-plus.md) - Default to Python 3.6 or newer for new development + + + +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] +* …