Skip to content

Commit d730bd6

Browse files
atextoratextor
authored
Add SAMM 2.2.0 release notes (#329)
* Clarify "namespace main part" as term in URNs This is to make it consistent with ADR 0007. * Add release notes for SAMM 2.2.0.
1 parent a5e0c54 commit d730bd6

File tree

2 files changed

+129
-9
lines changed

2 files changed

+129
-9
lines changed

‎documentation/modules/ROOT/pages/namespaces.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,16 +50,16 @@ Identifiers of elements that are defined on the model level -- i.e., Aspects, Pr
5050
Operations, Characteristics, Events, Units -- _must_ use the following schema:
5151

5252
....
53-
urn:samm:<namespace>:<version>#<element-name>
53+
urn:samm:<namespace-main-part>:<version>#<element-name>
5454
....
5555

5656
where the variable parts are interpreted as follows:
5757

58-
* *namespace* -- Defines the hierarchical namespace in which the element resides. This is given in
58+
* *namespace-main-part* -- Defines the hierarchical namespace part in which the element resides. This is given in
5959
https://en.wikipedia.org/wiki/Reverse_domain_name_notation[Reverse Domain Name Notation]. To
6060
avoid confusion with the {meta-model-full-name}, this _should not_ start with
6161
`org.eclipse.esmf` (unless for the model elements defined by the ESMF
62-
project, such as those that are part of SAMM). A namespace shall always be in lowercase.
62+
project, such as those that are part of SAMM). A namespace main part shall always be in lowercase.
6363
It should also contain at least two ASCII letters and should have at least two parts. So a minimal example of a namespace would be 'io.om'.
6464
* *version* -- The version of the respective namespace, must be given in the form "X.Y.Z", with X, Y
6565
and Z being integers.

‎documentation/modules/release-notes/pages/release-notes.adoc‎

Lines changed: 126 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,126 @@ SPDX-License-Identifier: MPL-2.0
1313
[[release-notes]]
1414
= Release Notes - {meta-model-full-name}
1515

16+
[[samm-2.2.0]]
17+
== Release 2.2.0
18+
19+
[[samm-2.2.0-modeling-features]]
20+
=== Modeling features and elements
21+
22+
* It is now possible to add `samm:preferredName`, `samm:description` and `samm:see` descriptive
23+
attributes to namespaces using the `samm:Namespace` pseudo-element declaration. A corresponding
24+
section xref:ROOT:modeling-guidelines#declaring-namespaces[Declaring Namespaces] was added.
25+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/246[Issue on Github.]
26+
27+
* Introduce new xref:ROOT:entities.adoc#quantity-entity[samm-e:Quantity] Abstract Entity to enable
28+
xref:ROOT:modeling-guidelines.adoc#declaring-quantities[declaring] explicit relationships between
29+
values and their units in runtime data.
30+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/316[Issue on Github.]
31+
32+
* Allow declaration and description of scalar values by introducing
33+
xref:ROOT:modeling-guidelines.adoc#value-type[samm:Value].
34+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/52[Issue on Github.]
35+
36+
[[samm-2.2.0-validation]]
37+
=== Validation
38+
39+
* xref:ROOT:characteristics.adoc#regular-expression-constraint[samm-c:RegularExpressionConstraint]s
40+
are now validated for `samm:exampleValue`. https://github.com/eclipse-esmf/esmf-sdk/issues/384[Issue
41+
on Github.]
42+
43+
* Validate that xref:ROOT:characteristics.adoc#constraint[samm:Constraint] base Constraint can not
44+
directly be used. https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/274[Issue
45+
on Github.]
46+
47+
* Validate lexical values for `xsd:boolean` and language tags for `rdfs:langString`.
48+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/268[Issue on Github.]
49+
50+
* Validate xref:ROOT:namespaces.adoc[structure of URNs].
51+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/285[Issue on Github.]
52+
53+
[[samm-2.2.0-documentation]]
54+
=== Documentation
55+
56+
* Clarification of terms and sections
57+
58+
** Consistent use of terms "must" and "should" in the documentation.
59+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/249[Issue on Github.]
60+
61+
** Clarify usage of
62+
xref:ROOT:modeling-guidelines.adoc#declaring-abstract-entities[samm:AbstractEntity] as a data
63+
type. https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/187[Issue on Github.]
64+
65+
** Update documentation on contradicting
66+
xref:ROOT:characteristics.adoc#length-constraints[samm-c:LengthConstraint]s.
67+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/267[Issue on Github.]
68+
69+
** Clarify validity of models where
70+
xref:ROOT:characteristics.adoc#length-constraints[samm-c:LengthConstraint]s are combined with
71+
xref:ROOT:characteristics.adoc#collection-characteristic[samm-c:Collection]s.
72+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/288[Issue on Github.]
73+
74+
** Clarify terms "scale" and "integer" for
75+
xref:ROOT:characteristics.adoc#fixed-point-constraint[samm-c:FixedPointConstraint].
76+
https://github.com/eclipse-esmf/esmf-sdk/issues/217[Issue on Github.]
77+
78+
** Specify in detail how prefixes are interpreted in `samm:curie`
79+
xref:ROOT:datatypes.adoc#samm-curie[values].
80+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/252[Issue on Github.]
81+
82+
** Fix xref:ROOT:datatypes.adoc[example value] for `xsd:int`.
83+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/283[Issue on Github.]
84+
85+
** Fix xref:ROOT:modeling-guidelines#declaring-time-series[samm-c:TimeSeries] example.
86+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/313[Issue on Github.]
87+
88+
** Clarify usage of `xsd` and `rdfs` RDF xref:ROOT:namespaces.adoc#prefixes[prefixes].
89+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/275[Issue on Github.]
90+
91+
** Clarify use of `samm:see` for IRDIs in section
92+
xref:ROOT:modeling-guidelines.adoc#adding-external-references[Adding external references].
93+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/320[Issue on Github.]
94+
95+
* Improvements of xref:ROOT:payloads.adoc[JSON payload mapping] section
96+
97+
** Provide example for xref:ROOT:payloads.adoc#example[JSON payload mapping].
98+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/121[Issue on Github.]
99+
100+
** Document xref:ROOT:payloads.adoc#characteristics-payload-mappings[mapping] of
101+
xref:ROOT:characteristics.adoc#either-characteristic[samm-c:Either] Characteristic to JSON payloads.
102+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/271[Issue on Github.]
103+
104+
* Improvements of xref:appendix:best-practices.adoc[Best Practices]
105+
106+
** Greatly improved best practices section on the topics of naming elements, choosing appropriate
107+
`samm:preferredName`&#8203;s and writing good `samm:description`&#8203;s. The best practices for
108+
descriptions now also state which https://commonmark.org/[CommonMark] Markdown constructs can be
109+
used for structuring documentation.
110+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/309[Issue on Github.]
111+
112+
** Add a best practices section on SI vs. imperial units.
113+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/273[Issue on Github.]
114+
115+
** Explain xref:appendix:best-practices.adoc#reusing-elements[Reusing Elements] in
116+
best practices. https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/328[Issue
117+
on Github.]
118+
119+
* Architecture decision records
120+
121+
** Define mapping of namespaces and model elements to files:
122+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0007-model-resolution.md[0007 - Model Resolution].
123+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/181[Issue on Github.]
124+
125+
** Specify how copyright and license information is stored in Aspect Models:
126+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0008-copyright-and-license-information.md[0008 - Storage of copyright and license information in Aspect Models].
127+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/300[Issue on Github.]
128+
129+
[[samm-2.2.0-others]]
130+
=== Others
131+
132+
* The xref:ROOT:meta-model-elements.adoc[Meta Model Elements] diagram is now colored.
133+
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/290[Issue on Github.]
134+
135+
16136
[[samm-2.1.0]]
17137
== Release 2.1.0
18138

@@ -41,14 +161,14 @@ https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/161[Issue
41161

42162
* Architecture decision records were added to properly document important past design decisions.
43163
https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/pull/243[Issue on Github].
44-
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0001-formalism-for-aspect-models.md[Formalism for the definition of Aspect Models: RDF with Turtle syntax]
45-
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0002-aspect-model-file-extension.md[Aspect
164+
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0001-formalism-for-aspect-models.md[0001 - Formalism for the definition of Aspect Models: RDF with Turtle syntax]
165+
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0002-aspect-model-file-extension.md[0002 - Aspect
46166
Model File Extension: Use .ttl]
47-
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0003-meta-model-specification.md[Formal and informal Meta Model Specification: Specify via SHACL]
48-
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0004-urn-as-identifiers.md[Usage
167+
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0003-meta-model-specification.md[0003 - Formal and informal Meta Model Specification: Specify via SHACL]
168+
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0004-urn-as-identifiers.md[0004 - Usage
49169
of URNs as identifiers for model elements]
50-
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0005-rdf-vocabulary.md[Aspect Meta Model RDF Vocabulary]
51-
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0006-unit-catalog.md[Unit Catalog: Use UNECE Recommendation 20]
170+
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0005-rdf-vocabulary.md[0005 - Aspect Meta Model RDF Vocabulary]
171+
** https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/blob/main/documentation/decisions/0006-unit-catalog.md[0006 - Unit Catalog: Use UNECE Recommendation 20]
52172

53173
* Section on xref:ROOT:modeling-guidelines.adoc#declaring-events[Declaring
54174
Events] was added; wrong edges in the xref:ROOT:meta-model-elements.adoc[Meta

0 commit comments

Comments
 (0)