From 951c131c04ccfc9a51353b131ed636d4f7d3b190 Mon Sep 17 00:00:00 2001 From: Andreas Hubel Date: Mon, 26 Sep 2022 22:40:56 +0200 Subject: [PATCH] draft / demo for ADRs --- architecture_decisons/.adr-dir | 1 + architecture_decisons/.template.md | 78 ++++++++++++ .../0000-record-architecture-decisions.md | 19 +++ architecture_decisons/0001-untagged-nodes.md | 76 ++++++++++++ .../0002-create-area-type.md | 111 ++++++++++++++++++ .../0003-restrict-strings.md | 83 +++++++++++++ 6 files changed, 368 insertions(+) create mode 100644 architecture_decisons/.adr-dir create mode 100644 architecture_decisons/.template.md create mode 100644 architecture_decisons/0000-record-architecture-decisions.md create mode 100644 architecture_decisons/0001-untagged-nodes.md create mode 100644 architecture_decisons/0002-create-area-type.md create mode 100644 architecture_decisons/0003-restrict-strings.md diff --git a/architecture_decisons/.adr-dir b/architecture_decisons/.adr-dir new file mode 100644 index 0000000..9c558e3 --- /dev/null +++ b/architecture_decisons/.adr-dir @@ -0,0 +1 @@ +. diff --git a/architecture_decisons/.template.md b/architecture_decisons/.template.md new file mode 100644 index 0000000..ab1c536 --- /dev/null +++ b/architecture_decisons/.template.md @@ -0,0 +1,78 @@ +# {short title of solved problem and solution} + +## Context and Problem Statement + +{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. + You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.} + + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, …} +* {decision driver 2, e.g., a force, facing concern, …} +* … + +## Considered Options + +* {title of option 1} +* {title of option 2} +* {title of option 3} +* … + +## Decision Outcome + +Chosen option: "{title of 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 one or more desired qualities, …} +* … + + +### Negative Consequences + +* {e.g., compromising one or more desired qualities, …} +* … + + +## Pros and Cons of the Options + +### {title of option 1} + + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} + +* Neutral, because {argument c} +* Bad, because {argument d} +* … + +### {title of other option} + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +## Validation + +{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} + + +## More Information + +{You might want to provide additional evidence/confidence for the decision outcome here and/or + document the team agreement on the decision and/or + define when this decision when and how the decision should be realized and if/when it should be re-visited and/or + how the decision is validated. + Links to other decisions and resources might here appear as well.} + + \ No newline at end of file diff --git a/architecture_decisons/0000-record-architecture-decisions.md b/architecture_decisons/0000-record-architecture-decisions.md new file mode 100644 index 0000000..4eb3b27 --- /dev/null +++ b/architecture_decisons/0000-record-architecture-decisions.md @@ -0,0 +1,19 @@ +# 1. Record architecture decisions + +Date: 2022-09-26 + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made on this project. + +## Decision + +We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). + +## Consequences + +See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools). diff --git a/architecture_decisons/0001-untagged-nodes.md b/architecture_decisons/0001-untagged-nodes.md new file mode 100644 index 0000000..c8ee985 --- /dev/null +++ b/architecture_decisons/0001-untagged-nodes.md @@ -0,0 +1,76 @@ +# Untagged Nodes + +## Context and Problem Statement + +{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. + You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.} + + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, …} +* {decision driver 2, e.g., a force, facing concern, …} +* … + +## Considered Options + +* {title of option 1} +* {title of option 2} +* {title of option 3} +* … + +## Decision Outcome + +Chosen option: "{title of 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 one or more desired qualities, …} +* … + + +### Negative Consequences + +* {e.g., compromising one or more desired qualities, …} +* … + + +## Pros and Cons of the Options + +### Getting rid of nodes + + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} + +* Neutral, because {argument c} +* Bad, because {argument d} +* … + +### {title of other option} + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +## Validation + +{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} + + +## More Information + +{You might want to provide additional evidence/confidence for the decision outcome here and/or + document the team agreement on the decision and/or + define when this decision when and how the decision should be realized and if/when it should be re-visited and/or + how the decision is validated. + Links to other decisions and resources might here appear as well.} \ No newline at end of file diff --git a/architecture_decisons/0002-create-area-type.md b/architecture_decisons/0002-create-area-type.md new file mode 100644 index 0000000..8548443 --- /dev/null +++ b/architecture_decisons/0002-create-area-type.md @@ -0,0 +1,111 @@ +# Creating an Area Data Type + +## Context and Problem Statement + +{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. + You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.} + +This ADR is about creating one or more area data types. We are using the word “area” on purpose here, and not (multi)polygon, to make sure we don’t mix it up with the (Multi)Polygon datatype defined by the Simple Features model. + + + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, …} +* {decision driver 2, e.g., a force, facing concern, …} +* … + +## Considered Options + +* {title of option 1} +* {title of option 2} +* {title of option 3} +* … + +## Decision Outcome + +Chosen option: "{title of 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 one or more desired qualities, …} +* … + + +### Negative Consequences + +* {e.g., compromising one or more desired qualities, …} +* … + + +## Pros and Cons of the Options + +### Variant WAY-WITH-FLAG + +Add a “flag” to the existing way datatype. The flag specifies whether +this way is a “linear” way or a “area-type” way. For migration we can add another option “unknown” which all existing ways will initially have. For backwards-compatibility with existing systems which don’t understand the flag, it can easily be expressed as an `area=yes/no` tag. The disadvantage is that no inner rings or multiple outer rings are possible. + + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} + +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +### Variant POLYGON + +Introduce a Polygon datatype with geometry semantics as in the Simple Feature standard. This gives us inner rings and the compatibility with Simple Features. With nodes +which are compatible to Simple Feature Points and ways which are compatible to Simple Feature LineStrings, we have complete compatibility with (non-multi) Simple Feature geometries. + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +### Variant MULTIPOLYGON + +Introduce a MultiPolygon datatype with geometry semantics as in the Simple Feature standard. This gives us multiple outer and inner rings and the compatibility with +Simple Features. Most areas will still be non-multi polygons, but that’s a subset of MultiPolygons, so that’s no problem, we just have to make sure non-multi polygons are efficiently encoded in the file formats. + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +### {title of other option} + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +## Validation + +{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} + + +## More Information + +{You might want to provide additional evidence/confidence for the decision outcome here and/or + document the team agreement on the decision and/or + define when this decision when and how the decision should be realized and if/when it should be re-visited and/or + how the decision is validated. + Links to other decisions and resources might here appear as well.} \ No newline at end of file diff --git a/architecture_decisons/0003-restrict-strings.md b/architecture_decisons/0003-restrict-strings.md new file mode 100644 index 0000000..a26320f --- /dev/null +++ b/architecture_decisons/0003-restrict-strings.md @@ -0,0 +1,83 @@ +# {short title of solved problem and solution} + +## Context and Problem Statement + +The limits on string length in OSM are kind of weird. They are mostly a historical accident, not from any design. For somebody who wants to create robust software they are too large, especially for user names, tag keys, and roles. On the other hand, for tag values they might be too short for some of things we are doing with them. But we have been living with them for a long time and haven’t seen any problems, so maybe it’s better not to touch them. + +Tag keys are [typically short](https://taginfo.openstreetmap.org/reports/key_lengths#histogram) and when they are not they are often clearly bogus. A maximum length of 64 or 100 bytes would be possible. But note that key length has been growing due to ever more keys with colon-separated hierarchical keys which to some extent make up for the missing complex data types in OSM. Whether this is to be encouraged is another question. But this question is definitely tied to the question of how much structure we want to have in tags. + +For relation member roles the situation is similar to the keys, because roles should really be only used for structural information (like the inner/outer roles on multipolygon relations). In practice roles are often used as some kind of free-text marker which arguably is something to be cleaned up anyway. + + +## Decision Drivers + +* {decision driver 1, e.g., a force, facing concern, …} +* {decision driver 2, e.g., a force, facing concern, …} +* … + +## Considered Options + +* {title of option 1} +* {title of option 2} +* {title of option 3} +* … + +## Decision Outcome + +Chosen option: "{title of 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 one or more desired qualities, …} +* … + + +### Negative Consequences + +* {e.g., compromising one or more desired qualities, …} +* … + + +## Pros and Cons of the Options + +### Do nothing + +We think this is a topic where much more discussion in the community is needed before we make any changes. + + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} + +* Neutral, because {argument c} +* Bad, because {argument d} +* … + +### {title of other option} + +{example | description | pointer to more information | …} + +* Good, because {argument a} +* Good, because {argument b} +* Neutral, because {argument c} +* Bad, because {argument d} +* … + + +## Validation + +{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} + + +## More Information + +{You might want to provide additional evidence/confidence for the decision outcome here and/or + document the team agreement on the decision and/or + define when this decision when and how the decision should be realized and if/when it should be re-visited and/or + how the decision is validated. + Links to other decisions and resources might here appear as well.} + + \ No newline at end of file