Proposal: Versioning of libraries on ecaguide.org

Issue information

From user: rocketeerbkw

Contribution record

Fork management

Problem/Motivation

ECA models have an optional "version" field but there is no defined format or meaning to the value. It has no effect/impact on modeling or processing. It is left to the user to decide what/if it should mean anything.

There are models on ecaguide.org in the Library section and there are plans to provide more models, including working examples. It could be useful for users if models on the guide conformed to a standard version format. It would allows users to see if a model they looked at or used has been changed. It could also act as an example for the wider ECA ecosystem for how a version format could be used.

There are two categories for a version format: semantic and non-semantic. A semantic version provides some kind of information about the underlying model that's part of the version itself. A non-semantic version provides no information about the underlying model, it acts only as a way to differentiate between versions.

The possible versions that could be adopted are listed below.

Semantic

• Full SemVer: major.minor.patch.
  Pros: aligns with Drupal core and contrib version format. Easy to compare.
  Cons: Models don't have a "public api" so how do you define what changes are major/minor/patch. Lots of burden on the user to understand the model and correctly version it. High risk of differences of opinion between users/models on what part of version should change.
• Semi-semantic: logic.documentation. A logic change is anything that effects the processing of a model e.g., create/delete of event/condition/action, or any changes to parameters of event/condition/action, or any changes to flow. A documentation change is anything that doesn't effect processing e.g., name/documentation changes, or rearranging for better aesthetics.
  Pros: Format is well defined and would tell a user what kind of updates have been made to a model. Easy to compare.
  Cons: Puts burden on user to understand the model and correctly version it. Doesn't align with any other formats in the Drupal community.

Non-semantic

• Datestamp: ISO-8601 2022-01-01 or simple 20220101.
  Pros: Easy to set. Easy to compare.
  Cons: Users could infer that a model is "old," even if it's not broken. Can't release updates more than once per day.
• Commit Sha: 8sfk84k
  Pros: None?
  Cons: Difficult (impossible?) to set, since you have to define a version before you commit. No easy way to tell which model is "newer."
• Contents Hash: sha/crc/etc of the library.
  Pros: Possibility for being able to detect changes to model.
  Cons: Mostly the same as Commit Sha format.
• Simple Incrementing: v1 -> v2. Whole numbers only.
  Pros: Easy to set. Easy to compare.
  Cons: Least informative, useful only for knowing that a model has changed.

Proposed resolution

Libraries on ecaguide.org should use a Simple Incrementing version format. Additionally, a changelog should be incorporated using the Extension Properties.

Remaining tasks

1. Decide on a version format
2. Document format on ecaguide.org
3. Update libraries on ecaguide.org to use format