Proposal: Versioning of libraries on ecaguide.org

TL;DR

For ecaguide.org, I like the simplest version format of incrementing whole numbers: v1 -> v2. It informs users that a model they looked at or used before has changed, and doesn't require contributors to learn and parse changes into a meaningful version.

As I stated in the IS, there's a chance that a format we pick for the guide gets adopted more broadly. In that case I like the custom/semi-semantic format of logic.documentation. It provides some information about what has changed between versions, but requires contributors to correctly map the changes they made into the correct part of the version format.

I'm sure there are other options (like combining date + increment 20220101-1). And maybe there is another category besides (non)-semantic. Would be interested to see other options.

As mentioned in slack, I did some quick googling to see if any BPMN/Camunda resources had recommendations and didn't find anything.

+1 for the idea in general. and how about adding some sort of changelog to the individual model page alongside the simple incremental versioning you've suggested in #2 📌 Proposal: Versioning of libraries on ecaguide.org Fixed . that way the user would know the module has changed and what has changed?

This is an outstanding summary, thanks @rocketeerbkw for writing this up.

My preference is the Simple incrementing combined with @rkoller's suggestion of a changelog. This could be easily maintained like this:

The text from the documentation field is already being used in the ECA Guide and the "Tags" are used for categorization and search. There we can add another property "Changelog" to keep track of changes. I think this would make a great improvement to the library in the ECA Guide.

Updated the IS to reflect the consensus.

I'm working on the Drush command to update the models for the library by incorporating all the conclusions above.

There is one minor thing that came up regarding the changelog, because that's a simple textfield in the bpmn_io UI and therefore difficult to use for longer text once we get more revisions of one model. I suggest that we use one property for each revision with a naming convention: Changelog v1: some text to describe the version changes The next version of that model will then get an additional property Changelog v2: some text to describe the version changes and so on. In the ECA Guide, we can convert that into a single "Changelog" heading followed by a list of items.

I have implemented this, updated all the existing models and deployed the changes to the ECA Guide at https://ecaguide.org/library for your review.

After that, the only remaining part is to write up the guidelines so that future contributors know what to deliver.

Have just written the contribution guidelines for the library in the ECA Guide at https://ecaguide.org/library and I'd much appreciate some feedback as we can close this issue here, once that's been finalized.

Is the Drush command useful for these libraries? Should that be documented also?

Otherwise the page LGTM.

Thanks @rocketeerbkw for your feedback. The Drush command is only used by ourselves to prepare the export to the library. Don't think we need to document it at this point. Maybe later, this could be opened up for everyone to be used, but that would require some extra steps.

Automatically closed - issue fixed for 2 weeks with no activity.