release strategy, product lifecycle, and hot-fixes

[bwbohl]

I see great effort and contributions in how MEI develops. Nevertheless I think we should com up with better communication of:

• release strategy: when and how will releases be tied together and how are decisions being taken on the features and fixes they contain.
• product lifecycle: how long does MEI support (and consequently hotfix) previous releases, i.e. which versions of MEI are still being maintained and fixed if a bug arises
• hot-fixes: it sometime occurs that fixes are being applied to the develop branch that actually should have been considered hot-fixes, that also should be applied to the stable branch

One way of managing this is making more use of milestones (https://github.com/music-encoding/music-encoding/milestones). Question with those is: what about datelines or the release strategy

happy to discuss and collect ideas and thoughts concerning theses topics

[ahankinson]

I agree!

I would also like to add something about "development expectations" and "the lifecycle of an issue". It is clear that we are developing a specification, and this is something different than software (See my comment here: #843 (comment))

Namely, that once a change makes it in to the specification, there is a real-world implication for implementers down the line, and those changes usually are associated with a cost.

If a change is introduced in software and that results in a bug, the bug is fixed and the issue is closed.

However, if a change is not well thought-out in a specification, this specification is released, and it is implemented in data, then this data will persist indefinitely. "Bug fixes" to data are much, much harder than bug fixes to software. You can't just install a new version of the spec! So necessarily there must be greater oversight, more critique, and slower development cycles for specifications than for software.

For adding new features, we need to be aware that bad encodings will probably outlive all of us, so we need to spend time to get things right.

For removing features, we need to be aware that this means more work for projects that may not have much in the way of budget to keep their data upgraded, particularly if they want to use later versions of Verovio or other tools.

All this is to say that we should have a clear way of knowing, in our issue tracker, what is the next necessary step to move something forward, and possibly a 'cooling off' period that a PR sits before it gets merged, so that we can ensure broad consensus and visibility. This is so that we can manage expectations of how long a particular change will take: It is frustrating, as a contributor, to be in limbo about what state your particular contribution is in, and what might need to be done to move it forward. Particularly if you're used to shorter turnaround times in software development.

I have seen this done with issue 'lifecycle' diagrams:

• https://www.cappuccino.dev/contribute/issue-lifecycle.html.
• https://github.com/microsoft/botframework-solutions/wiki/Issue-lifecycle
• https://github-wiki-see.page/m/emfoundation/asset-manager/wiki/Issue-Lifecycle-(Labels)

Indeed, this is what the current set of labels tries to do, but it is lacking in communication of the flow of an issue through the process.

[bwbohl]

@ahankinson thanks for the valuable input especially considering graphical documentation of issue or pull request lifecycle!

[bwbohl]

Some general follow up questions:

1. Do you deem it possible to e.g. come up with something like thematic releases in MEI, e.g. let's say a release milestone around the topic »text representation« that would only include features an fixes concerning word-text encoding in MEI, say titles, title pages, directions, verse but also in the scope of metadata, e.g. source description or exihbHist (to pick from a more recent issue) etc. Or a release specifically concentrating on building and build automation.

2. What could support of older MEI versions mean? Considering music-encoding.org/guidelines we offer the latest stable (MEI 4), the preceding release (MEI 3), and the current development version. If. that is something that we could agree upon in terms of ‘product lifecycle’, what would be the consequences? If…

   • someone spots a bug in the preceding release (MEI 3)? If so, that would mean to check it in MEI 4, too? Should it get fixed in both? And consequently in dev, too? Would that mean to re-release the guidelines, too? Should the buggy versions of the schemata and guidelines be kept in the guidelines and schemata repositories or should those be replaced by the amended versions?

[ahankinson]

I'll answer the second one first:

An MEI version is, for all intents and purposes, a standalone version. 4.0 is different from even 4.0.1, if the @meiversion statement says it is. This is not software, this is a document standard. You can't just "install" a new version of MEI and all your documents are automatically updated. If your documents use the buggy part of the spec, then you still have to do the work of updating your documents to the new version.

What we do guarantee with patch releases is a minimal amount of backwards compatibility, but I think this is primarily designed for software developers. Software that is "compatible" with 4.0 should also work with 4.0.1, since no breaking change should have been made between the two.

So we "support" MEI 3 now, in roughly the same way we "support" it when it was first released. If you encoded files in MEI 3 and they validated then, then they will continue to validate with MEI 3. I think also, if someone has a big enough corpus of files encoded in MEI 3 and they find a bug, they can either a) pay for their project to upgrade their own files, or b) pay for a developer to patch the bug and ask the community to release 3.0.N. I think the best option is option A for most projects.

If the bug also exists in the latest, and next, versions then yes -- this should be fixed.

The answer to the first question is more about what we should expect from the community. If the Metadata IG comes up with a bunch of core changes and deprecates elements, then that necessitates a major version change. When we release is then a matter of who is able to get their changes in according to a given, but probably somewhat arbitrary, timeline. I'm not sure about thematic releases: I haven't really thought about it too much. My first instinct is that it would probably create artificial pressure on groups to "just release something" without having time and consultative space with the wider community, and then we're back to bug-fixing a spec that might have hundreds or thousands of files that require it.

I don't think we can necessarily do more "rolling releases" like software, where bug fixes are just released when ready. This will be too much work for the community to keep up with the specs. MEI is a root dependency for a lot of projects, so changing the version, even a minor one, will then trigger many changes down through the ecosystem. A lot of releases means then a lot of churn for all the different software and edition projects, most of which are run on volunteer efforts.

Releases focused on builds or build automation that don't touch the spec are probably not worth even tagging as a release. Or, some communities add addenda to their version numbers, like. 0.19.1-5, which is to say that it's the fifth release of 0.19.1. MEI would look something like "4.0.1-2". This would mean that @meiversion would still be 4.0.1, but we could release non-spec related changes that deal with infrastructure or guidelines within that that would increment the -2 portion.

That's one example I've seen. It gets a bit nutso with the version numbers, but it does provide some flexibility. Another one we could do is just shift the numbers and restrict the value of @meiversion to only two digits: 4.0, 4.1, etc. Then we're able to use the last component to tag non-spec releases. This would be breaking semantic versioning, since we might release a 'patch' version as a X.N update, but it would mean using only three digits while still having the flexibility of the other method.

[lpugin]

There were some discussions during the conference last week about the plans for the next version of MEI - now that MEI 5.0 is out!

One idea that emerged was to make sure we would not make compatibility breaking changes to the schema for a while in order to have the possibility to have an MEI 5.1 release within a time frame that would range between a few months from now to a year.

Non breaking compatibility changes include (at least):

• Improvement to the guidelines
• Changes to the way things are expressed but with no differences in the resulting MEI schema
• Changes that introduce new attribute values, new attributes or new elements
• Changes that expand ways elements can be included (e.g., allowing for an element to have more children of a type than before)
• Changes that allow for some elements to be empty

Of course, this means for the PRs to be thoroughly reviewed accordingly (e.g., this PR with a label MEI 6 should not be merged yet) since the rule of thumb would be that any MEI 5.0 file should remain valid with MEI 5.1.

I am posting this here not implying that this should be a common pattern in the release strategy, but since we had such a long gap between MEI 4.0.1 and MEI 5.0, but at the same time many open issues / PR with MEI 5.x label, it seems that it would be a valuable approach in this particular case.

[bwbohl]

thx for sharing our thoughts to a broader audience ;-)

[ahankinson]

Managing and distinguishing breaking / non-breaking changes is really difficult, as we've found out over the past few years.

Also, and I feel I need to continually state this, releasing a new MEI version is a significant event that requires a lot of work to update software in the ecosystem. Some tools, like Verovio, are able to accommodate this pretty easily. For a good deal others, like the various workflows for all the digital editions, this represents a major undertaking.

MEI is a specification, not software, so it needs to move slower so that we're not causing a lot of unnecessary churn as people try to update their tooling.

As a result, I'm still thinking that we simplify considerably:

• @meiversion should be restricted to single numbers. meiversion="5", meiversion="6", meiversion="7", etc. . This would mean that there would be a very clear, stable schema that projects can use until they choose to update, and that schema will not change.
• Any release would be a major increment. Whether we want to do this yearly, or every two years, is up to us, and whether there are a lot of pending changes.
• Any merge of develop to stable is a major release. It doesn't matter if it changes existing functionality, or adds new functionality. Keeping track of the distinction, and actually agreeing that there is a distinction, has been shown to be very hard to do, so we can choose to just not do it and save ourselves the hassle.
• Any updates required to fix things in the released version can get a tag, for reference, but would not change the version number. So if we need to fix typos or mechanics for building in the GH Actions in the current MEI version "stable" branch, the GitHub tag for the new version would be "v5.0-1", "v5.0-2", etc., signifying that it's still version 5, but that something has changed in the stable branch. If we move to single-digit versioning in v6, then the tag might be v6-1, v6-2, etc. But we could also keep the v6.0-1 tag form too. That doesn't matter much.