From 82718652e7f80dd586997bdcf48789306a2f3fa3 Mon Sep 17 00:00:00 2001 From: Stefan Kapferer Date: Thu, 4 May 2023 13:15:32 +0200 Subject: [PATCH 1/2] First MADRs for latest decisions --- ...0001-domain-services-outside-aggregates.md | 26 +++++++++++++++++++ docs/madr/0002-use-case-diagram-layout.md | 20 ++++++++++++++ docs/madr/README.md | 5 ++++ 3 files changed, 51 insertions(+) create mode 100644 docs/madr/0001-domain-services-outside-aggregates.md create mode 100644 docs/madr/0002-use-case-diagram-layout.md create mode 100644 docs/madr/README.md diff --git a/docs/madr/0001-domain-services-outside-aggregates.md b/docs/madr/0001-domain-services-outside-aggregates.md new file mode 100644 index 00000000..00bebedb --- /dev/null +++ b/docs/madr/0001-domain-services-outside-aggregates.md @@ -0,0 +1,26 @@ +--- +status: "accepted" +date: "2023-04-06" +deciders: "stefan-ka, socadk" +--- +# Allow modeling of domain services besides aggregates, instead of inside aggregates + +## Context and Problem Statement + +We originally took the [Sculptor DSL](http://sculptorgenerator.org/) for the tactic DDD part. For some reason we do not exactly know, they decided that services are modelled inside aggregates. This does not correspond with our interpretation of the DDD patterns and was additionally reported with [#326](https://github.com/ContextMapper/context-mapper-dsl/issues/326). Domain services should be modeled on the same level as aggregates (for CML, this means inside the bounded context object). + +The problem: correcting this issue in a clean way would lead to a non-backwards-compatible change. + +## Considered Options + +* Not backwards-compatible: Make non-backwards-compatible change and release a new major version of Context Mapper. +* Backwards-compatible: Allow to model domain services inside bounded contexts, but still support the old option to stay backwards-compatible. + +## Decision Outcome + +Chosen option: "backwards-compatible", because a breaking change is risky, causes a lot of documentation work for us, and lots of migration work for the users (adjust their models). + +### Consequences + +* Good, because we lower the risk and cause less migration and documentation work for us and the users. +* Bad, because it is still possible to model domain services in a way that does not reflect our understanding of the patterns. diff --git a/docs/madr/0002-use-case-diagram-layout.md b/docs/madr/0002-use-case-diagram-layout.md new file mode 100644 index 00000000..68b7037c --- /dev/null +++ b/docs/madr/0002-use-case-diagram-layout.md @@ -0,0 +1,20 @@ +--- +status: "accepted" +date: "2023-05-04" +deciders: "stefan-ka, socadk" +--- +# Layout for Use Case Diagrams (PlantUML Generator) + +## Context and Problem Statement + +While implementing our Use Case diagram generator, we realised that there are some differences regarding how people visualize use case diagrams. The [PlantUML documentation](https://plantuml.com/use-case-diagram) by default suggests that arrows point from actors to use cases. It does not clearly state how [secondary actors](https://socadk.github.io/design-practice-repository/artifact-templates/DPR-UseCase.html) shall be visualized. socadk legitimately pointed out that for a secondary actor it would make more sense to point the arrow from the use case to the secondary actor, as only the primary actor initiates the use case. +Based on that discussion we checked out [Larman](https://www.amazon.de/Applying-UML-Patterns-Introduction-Object-Oriented/dp/0131489062); the "defacto" standard book for UML. Larman suggests to not make arrows but just connect the actors with the use cases and draw the primary actors on the left and secondary actors on the right. Use cases are visualized top to bottom. + +## Considered Options + +* Default PlantUML with arrows +* Stick to Larman + +## Decision Outcome + +Chosen option: "Stick to Larman", because we usually tried to stick with the standard literature. For example: For the Context Map generator we tried to stick to the visualization of [Vaughn Vernon](https://www.amazon.de/s?k=implementing+domain+driven+design&adgrpid=63456564181&hvadid=381008329565&hvdev=c&hvlocphy=1030659&hvnetw=g&hvqmt=e&hvrand=11057192946270756118&hvtargid=kwd-299405302030&hydadcr=14770_1980674&tag=hydrach-21&ref=pd_sl_9tt0fqrrb3_e). Thereby, our decision is consistent with our earlier design principles. diff --git a/docs/madr/README.md b/docs/madr/README.md new file mode 100644 index 00000000..b5ec2c4b --- /dev/null +++ b/docs/madr/README.md @@ -0,0 +1,5 @@ +# Markdown Any Decision Records (MADR) + +Within this folder we document our design and architectural decisions according to the [MADR template](https://github.com/adr/madr). + +To create a new record, use the template file [here](https://github.com/adr/madr/blob/develop/template/adr-template.md). From 43d62931390994be412b17c80cf9869d78ca416d Mon Sep 17 00:00:00 2001 From: Stefan Kapferer Date: Thu, 4 May 2023 18:26:44 +0200 Subject: [PATCH 2/2] review comments --- docs/madr/0002-use-case-diagram-layout.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/madr/0002-use-case-diagram-layout.md b/docs/madr/0002-use-case-diagram-layout.md index 68b7037c..a17ee674 100644 --- a/docs/madr/0002-use-case-diagram-layout.md +++ b/docs/madr/0002-use-case-diagram-layout.md @@ -8,7 +8,7 @@ deciders: "stefan-ka, socadk" ## Context and Problem Statement While implementing our Use Case diagram generator, we realised that there are some differences regarding how people visualize use case diagrams. The [PlantUML documentation](https://plantuml.com/use-case-diagram) by default suggests that arrows point from actors to use cases. It does not clearly state how [secondary actors](https://socadk.github.io/design-practice-repository/artifact-templates/DPR-UseCase.html) shall be visualized. socadk legitimately pointed out that for a secondary actor it would make more sense to point the arrow from the use case to the secondary actor, as only the primary actor initiates the use case. -Based on that discussion we checked out [Larman](https://www.amazon.de/Applying-UML-Patterns-Introduction-Object-Oriented/dp/0131489062); the "defacto" standard book for UML. Larman suggests to not make arrows but just connect the actors with the use cases and draw the primary actors on the left and secondary actors on the right. Use cases are visualized top to bottom. +Based on that discussion we checked out [Larman](https://www.amazon.de/Applying-UML-Patterns-Introduction-Object-Oriented/dp/0131489062); a popular book on UML and OOAD, serving as a 'de-facto' standard for many modelers. Larman suggests to not make arrows but just connect the actors with the use cases and draw the primary actors on the left and secondary actors on the right. Use cases are visualized top to bottom. ## Considered Options @@ -17,4 +17,4 @@ Based on that discussion we checked out [Larman](https://www.amazon.de/Applying- ## Decision Outcome -Chosen option: "Stick to Larman", because we usually tried to stick with the standard literature. For example: For the Context Map generator we tried to stick to the visualization of [Vaughn Vernon](https://www.amazon.de/s?k=implementing+domain+driven+design&adgrpid=63456564181&hvadid=381008329565&hvdev=c&hvlocphy=1030659&hvnetw=g&hvqmt=e&hvrand=11057192946270756118&hvtargid=kwd-299405302030&hydadcr=14770_1980674&tag=hydrach-21&ref=pd_sl_9tt0fqrrb3_e). Thereby, our decision is consistent with our earlier design principles. +Chosen option: "Stick to Larman", because we try to use and align with the literature as such as possible. For example: For the Context Map generator we tried to stick to the visualization of [Vaughn Vernon](https://www.amazon.de/s?k=implementing+domain+driven+design&adgrpid=63456564181&hvadid=381008329565&hvdev=c&hvlocphy=1030659&hvnetw=g&hvqmt=e&hvrand=11057192946270756118&hvtargid=kwd-299405302030&hydadcr=14770_1980674&tag=hydrach-21&ref=pd_sl_9tt0fqrrb3_e). Thereby, our decision is consistent with our earlier design principles.