search

opencaesar / oml

Ontological Modeling Language (OML)
https://opencaesar.github.io/oml/
Apache License 2.0
23 stars 4 forks source link

Add link in oml2 spec to upgrade notes #113

Open mprather opened 8 months ago

mprather commented 8 months ago

User Story

Users need to be aware that v2 is a breaking change relative to v1.

In reading the default spec (which is v2), a user cannot discern that they will not be able to upgrade from v1. This seems like a pretty big knowledge gap, especially for the user that is coming from a v1 project.

Suggestions:

  1. v2 spec needs to call out that it is a breaking change from v1.
  2. v2 spec should reference whatever documentation serves as the authoritative upgrade list (e.g. https://www.opencaesar.io/projects/2023-7-21-OML-v2.html)
melaasar commented 8 months ago

Isn't this the point of a major revision (v1 -> v2) that breaking interface changes are expected? Otherwise, it would have been a minor revision. (see definitions in https://semver.org/).

The OML textual syntax, abstract syntax, and Java API, are all interface of OML.

Does this make sense?

mprather commented 8 months ago

No, I don't agree that reliance on simver is an explicit clear-cut case. I've seen a ton of libraries where a portion might break but major functionality remained even though the major changed. Thus, in those cases, upgrade was possible without having to rework code to fit. In this case, OML v2 is 100% incompatible with v1.

This information needs to be documented. I've worked with too many libraries over the past 3 decades to know that version documentation should call out what it takes to upgrade.

melaasar commented 8 months ago

I added a Version Migration section to the spec: https://www.opencaesar.io/oml/#Version-Migration

If this addresses your request, please close the issue.