Plugin versioning pattern/semver adoption

[jonasraoni]

Small discussion about versioning, here's the context: https://github.com/pkp/pln/blob/main/version.xml#L16

Sparing a range to avoid the versions to overlap (looks like we already have some cases) across different branches ends up breaking the versioning meaning.
I'm used to have a unified version/branch and adapt the code to work on other places with the help of "#ifdefs", but that's not suitable for our use-case, the version for 3.4 might have more features than the one for 3.3 for example, and they can co-exist for a long time.

Ideas:

• An extra tag in the version.xml stating its compatibility, which is useful when installing the plugin, and can be also re-used by the plugin gallery (instead of adding the such information on the plugins.xml):

  <compatibility application="ojs">
   <version>~3.4.0.0</version>
  </compatibility>

• Drop the 4 digits version (w.x.y-z) in favor of semver, it has room for pre-release and metadata tags.

ctgraham
Yes to plugins declaring their compatibility within version.xml as a dedicated tag!

Note that this will soon be much easier as we can now support composer/semver constraint statements: #7793

p.s.: rescued from a Slack conversation

[marcbria]

Aunque a priori no se me ocurre ningún problema en cambiar de 4 dígitos a semver, comentar (por ver las ramificaciones) que las imágenes docker usan los mismos nombres de versión que las herramientas OxS.

[ctgraham]

Note that our Version object is now aware of semver.

If the plugin's version.xml contained a semver-based version declaration, and a semver-based compatibility declaration, then future entries in the Plugin Gallery would not need to re-produce this information by hand, and this information could be used during the installation process to sanity check the addition of plugins, even when unknown to the Plugin Gallery.

[marcbria]

I’d like to undust this conversation to propose a solution that I believe resolves the mentioned issues (and hopefully doesn’t create new ones). :-P

• On one hand, plugins need to indicate which version of OJS they are compatible with.
• On the other hand, plugins also need to indicate their own version.

From discussions on Mattermost, it’s clear that:

1. The plugin’s versioning should not be directly tied to the OJS version.
2. Plugins should follow their own semver scheme.
3. Separate branches should be used for each main OJS version (3.2, 3.3, 3.4, etc.), rather than having different repositories or a single branch compatible with multiple versions.
4. Not following these principles can lead to namespace collisions (as has already happened recently with sword plugin).

In this sense, why not use branches to indicate the OJS version and tags to indicate the plugin version?

The solution:

• Completely separates OJS and plugin versions.
• It's simple to explain and adopt.
• Allows end users to go directly to the plugin version they need (and also makes it easier to maintain version.xml for the plugin gallery).
• Developers can still use GitHub’s automatic packaging to generate plugin releases (ZIPs) from tags.

From what I’ve seen, some developers have already started adopting this approach in their new plugins.

Can we reach a consensus to recommend this practice to new developers?

[jonasraoni]

1. Yes, the application compatibility should be specified separately.
2. Agreed.
3. I'm not sure this is a best practice, if the code is the same, I don't see a reason to create extra branches, it's a maintenance burden (which we're doing at PKP)... The main problem is that we're breaking the application code too often (and not respecting the semver?!), if we stop doing it, plugins are supposed to have a more independent/longer life. The answer for this would be a more modular system (specific packages instead of a large pkp-lib).
4. I don't know what happened there 👀

In this sense, why not use branches to indicate the OJS version and tags to indicate the plugin version?

I see this just as a Git organization, whoever is using the GitHub release system is already making use of tags, so the only addition will be the branch = supported application version, right?

I'd say this discussion can be closed by this issue: #7531

I think the application should warn the user when attempting to install an incompatible (or "unknown", when missing the new tag) plugin, but it should be possible to ignore the warning (possibly controlled by a config setting allow_incompatible_plugins).