Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How to deal with minimal model updates #169

Merged
merged 4 commits into from
Jun 6, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/ISSUE_TEMPLATE/model_update_request.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ labels: update
- [ ] The model that should be updated exists
- [ ] The referenced use case exists
- [ ] The potential updates are discussed with all stakeholders
- [ ] A decision on versioning was made in consensus with the affected parties [according to the guidelines](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/documentation/GOVERNANCE.md#versioning).
- [ ] The potential update will be either
- [ ] backward compatible or
- [ ] a (chain of) migration strategy(-ies) from all non-deprecated previous versions to the new model will be developed
17 changes: 17 additions & 0 deletions documentation/GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,20 @@ Modeling_Team
to the PR. We have filters, which check for such comments.
## Retiring a model
Once a model gets the status "DEPRECATED" it should not be used anymore by new use cases. Existing applications should look for a way to migrate to an alternative version or model. In alignment with the overall release cycles of Tractus-X, the modeling team tags the current main branch with the corresponding Tractus-X release and publishes modeling release notes. These release notes contain a hint about all model versions that changed the status to "DEPRECATED" since the previous Tractus-X release. The modeling team will delete these models two Tractus-X releases cycles later. So use cases are advised to react to the deprecation of models within the next release cycle.

## Versioning
The semantic modeling in Tractus-X follows [Semantic Versioning](https://semver.org/). Since the version is included in the Aspect Model's URI
(i.e. `urn:bamm:io.catenax.batch:1.0.2#Batch`), applications that work on the model may have incompatible API-changes even when the changes in the model
are marginal. The same phenomenon may occur with the [CX-standard-documents](https://catena-x.net/de/standard-library) that reference
a semantic model. Inspired by the definitions of SemVer, the following best practices shall be followed here:

- No increment: Trivial changes that do not affect the functional parts of the model may be changed via PR without an incremented version number.
Changes must not affect the functional generated json-schema. This particularly applies to copyright-headers and descriptions,
as long as the descriptions do not change the inherent meaning of a Property/Trait etc.
- Patch: A patch is a change in the model that does not add or remove functionality. This could for example be
updating a model with an additional `bamm:see` attribute that has equivalent semantics to the aspect.
Standard documents must be adjusted to reflect the patched versions.
- Minor: There are no minor increments of aspect models.
- Major: Major increments are constituted by breaking API changes such as adding, removing or (in cumolo) renaming
elements (optional or non-optional) of a semantic model. Changing the meaning/semantics or the data type of an element
is a major change too.