From 3cadc317df32982600f93ef94397a6a1def7484d Mon Sep 17 00:00:00 2001 From: "Dr. Gernot Starke" Date: Sun, 13 Oct 2024 14:57:59 +0200 Subject: [PATCH 1/3] create ADR-008 to explain _wontfix_ of #597 --- .../008-specify-quality-requirements.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 documentation/decisions/008-specify-quality-requirements.md diff --git a/documentation/decisions/008-specify-quality-requirements.md b/documentation/decisions/008-specify-quality-requirements.md new file mode 100644 index 0000000..e262dba --- /dev/null +++ b/documentation/decisions/008-specify-quality-requirements.md @@ -0,0 +1,22 @@ +# 008: Architects are able to specify quality requirements + +## Status: Accepted + +## Context +Within the FOUNDATION level working group we had long (aka _endless_) discussions about quality and quality requirements. +Conclusion is: + +* Software architects shall be able to formulate precise quality requirements, i.e. as quality scenarios. +* The shall not _invent_ these, but formulate in cooperation or collaboration with other stakeholders. + +## Rationale: + +* The ability to formulate such requirements in precise and practically usable ways is part of many CPSA-Advanced level certifications, therefore it *must* be taught and practiced within foundation level trainings. + + +## Consequences: + +We discussed this topic within GitHub issues: + +* [#597](https://github.com/isaqb-org/curriculum-foundation/issues/597) proposed a somewhat weaker formulation (_know how to formulate scenarios..._). We decided to keep the existing "_are able to_". +* In [#501](https://github.com/isaqb-org/curriculum-foundation/issues/501) we decided to elevate quality scenarios to R1. \ No newline at end of file From c3b4f5d84afc08f0f7c4bcb8c71d9205083899b4 Mon Sep 17 00:00:00 2001 From: "Dr. Gernot Starke" Date: Sun, 13 Oct 2024 17:12:04 +0200 Subject: [PATCH 2/3] #564 LG-03-07 characteristics of interfaces --- docs/03-design/LG-03-07.adoc | 60 +++++++++++++++++++++++++++--------- 1 file changed, 46 insertions(+), 14 deletions(-) diff --git a/docs/03-design/LG-03-07.adoc b/docs/03-design/LG-03-07.adoc index f0b1784..01730ca 100644 --- a/docs/03-design/LG-03-07.adoc +++ b/docs/03-design/LG-03-07.adoc @@ -4,20 +4,36 @@ [[LG-03-07]] ==== LZ 03-07 [ehemaliges LZ 2-09]: Schnittstellen entwerfen und festlegen (R1-R3) -Softwarearchitekt:innen kennen die hohe Bedeutung von Schnittstellen. Sie können Schnittstellen zwischen Architekturbausteinen sowie externe Schnittstellen zwischen dem System und Elementen außerhalb des Systems entwerfen bzw. festlegen. +Softwarearchitekt:innen kennen die hohe Bedeutung von Schnittstellen. +Sie können Schnittstellen zwischen Architekturbausteinen sowie externe Schnittstellen zwischen dem System und Elementen außerhalb des Systems entwerfen bzw. festlegen. Sie kennen: -* wünschenswerte Eigenschaften von Schnittstellen und können diese bei ihrer Entwicklung einsetzen: +* wünschenswerte Eigenschaften von Schnittstellen und können diese bei ihrer Entwicklung einsetzen (R1): ** einfach zu erlernen, einfach zu benutzen, einfach zu erweitern ** schwer zu missbrauchen ** funktional vollständig aus Sicht der Nutzer:innen oder nutzender Bausteine. -* die Notwendigkeit unterschiedlicher Behandlung interner und externer Schnittstellen -* die Trennung zwischen Schnittstelle und Implementierung: + +* die Notwendigkeit unterschiedlicher Behandlung interner und externer Schnittstellen (R2) + +* die Trennung zwischen Schnittstelle und Implementierung (R1): ** Implementierungen können bei Bedarf ausgetauscht werden. -* unterschiedliche Implementierungsansätze von Schnittstellen (R3): -** ressourcenorientierter Ansatz (REST, REpresentational State Transfer) -** serviceorientierter Ansatz (wie bei WS-*/SOAP-basierten Webservices). + +* unterschiedliche Charakteristika von Schnittstellen, beispielsweise (R3): +** Transportkanäle (etwa: das OSI-7-Schichtenmodell oder TCP/IP) +** Intern oder extern +** lokal oder remote +** synchron oder asynchron +** binär (nur maschinenlesbar) oder textuell (auch menschenlesbar) +** zustandslos oder zustandsbehaftet +** Punkt-zu-Punkt oder Multipunkt (broadcast oder multicast) +** Funktionsaufruf (etwa: Remote Procedure Call) oder Nachrichtenaustausch +** Batch, Request/Response oder Streaming + +* unterschiedliche Implementierungsansätze von Schnittstellen, etwa (R3): +** ressourcenorientiert (REST, REpresentational State Transfer) +** graphenartiger (etwa: GraphQL) +** serviceorientiert (etwa: WS-*/SOAP-basierte Webservices) Siehe auch <>. // end::DE[] @@ -26,20 +42,36 @@ Siehe auch <>. [[LG-03-07]] ==== LG 03-07 [previously LG 2-09]: Design and Define Interfaces (R1-R3) -Software architects know about the importance of interfaces. They are able to design or specify interfaces between architectural building blocks as well as external interfaces between the system and elements outside of the system. +Software architects know about the importance of interfaces. +They are able to design or specify interfaces between architectural building blocks as well as external interfaces between the system and elements outside of the system. They know: -* desired characteristics of interfaces and can use them in the design: +* desired characteristics of interfaces and can use them in the design (R1): ** easy to learn, easy to use, easy to extend ** hard to misuse ** functionally complete from the perspective of users or building blocks using them. -* the necessity to treat internal and external interfaces differently -* the distinction between interface and implementation: + +* the necessity to treat internal and external interfaces differently (R2) + +* the distinction between interface and implementation (R1): ** implementations can be exchanged if required. -* different approaches for implementing interfaces (R3): -** resource oriented approach (REST, Representational State Transfer) -** service oriented approach (see WS-*/SOAP-based web services). + +* different characteristics of interfaces, for example (R3): +** Transport channels (for example: the OSI 7-layer model or TCP/IP) +** internal or external +** local or remote +** synchronous or asynchronous +** Binary (only machine-readable) or textual (also human-readable) +** stateless or stateful +** point-to-point or multipoint (broadcast or multicast) +** Function call (e.g. remote procedure call) or message exchange +** Batch, request/response or streaming + +* Different implementation approaches for interfaces, such as (R3:) +** resource-oriented (REST, REpresentational State Transfer) +** graph-oriented (e.g. GraphQL) +** service-oriented (e.g. WS-*/SOAP-based web services) See also <>. From ab81b56fc923757fea33377621fa8ef79760a5fa Mon Sep 17 00:00:00 2001 From: "Dr. Gernot Starke" Date: Wed, 16 Oct 2024 22:10:37 +0200 Subject: [PATCH 3/3] updated LG-03-07 with comments from PR --- docs/03-design/LG-03-07.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/03-design/LG-03-07.adoc b/docs/03-design/LG-03-07.adoc index 01730ca..a5f7f2d 100644 --- a/docs/03-design/LG-03-07.adoc +++ b/docs/03-design/LG-03-07.adoc @@ -2,14 +2,14 @@ // tag::DE[] [[LG-03-07]] -==== LZ 03-07 [ehemaliges LZ 2-09]: Schnittstellen entwerfen und festlegen (R1-R3) +==== LZ 03-07 [ehemaliges LZ 2-09]: Schnittstellen entwerfen und spezifizieren (R1-R3) -Softwarearchitekt:innen kennen die hohe Bedeutung von Schnittstellen. -Sie können Schnittstellen zwischen Architekturbausteinen sowie externe Schnittstellen zwischen dem System und Elementen außerhalb des Systems entwerfen bzw. festlegen. +Softwarearchitekt:innen kennen die kritische Bedeutung von Schnittstellen für die Interaktion zwischen Architekturbausteinen oder zwischen dem System und externen Elementen. +Sie können solche Schnittstellen entwerfen und spezifizieren. Sie kennen: -* wünschenswerte Eigenschaften von Schnittstellen und können diese bei ihrer Entwicklung einsetzen (R1): +* wünschenswerte Eigenschaften von Schnittstellen und können diese beim Entwurf erreichen (R1): ** einfach zu erlernen, einfach zu benutzen, einfach zu erweitern ** schwer zu missbrauchen ** funktional vollständig aus Sicht der Nutzer:innen oder nutzender Bausteine. @@ -32,7 +32,7 @@ Sie kennen: * unterschiedliche Implementierungsansätze von Schnittstellen, etwa (R3): ** ressourcenorientiert (REST, REpresentational State Transfer) -** graphenartiger (etwa: GraphQL) +** graphenartig (etwa: GraphQL) ** serviceorientiert (etwa: WS-*/SOAP-basierte Webservices) Siehe auch <>. @@ -42,12 +42,12 @@ Siehe auch <>. [[LG-03-07]] ==== LG 03-07 [previously LG 2-09]: Design and Define Interfaces (R1-R3) -Software architects know about the importance of interfaces. -They are able to design or specify interfaces between architectural building blocks as well as external interfaces between the system and elements outside of the system. +Software architects know the critical importance of interfaces for the interaction between architectural building blocks or between the system and external elements. +They can design and specify such interfaces. They know: -* desired characteristics of interfaces and can use them in the design (R1): +* desired characteristics of interfaces and can achieve them in the design (R1): ** easy to learn, easy to use, easy to extend ** hard to misuse ** functionally complete from the perspective of users or building blocks using them. @@ -58,7 +58,7 @@ They know: ** implementations can be exchanged if required. * different characteristics of interfaces, for example (R3): -** Transport channels (for example: the OSI 7-layer model or TCP/IP) +** Transport channels (for example: TCP/IP as part of the OSI-7 layer model, shared memory) ** internal or external ** local or remote ** synchronous or asynchronous