Adopt semantic versioning

Current Problem

Upgrading our websites to the latest security patches and bug fixes is a pain point
The commitment of "never introducing breaking changes" results in hard-to-maintain tech debt and constrains us by maintaining features that are no longer helpful. They could even be limiting (e.g. feature X can't be added because feature Y exists)
If we do have a breaking change (because they are ultimately inevitable), nothing is preventing a user from being stuck with breaking changes when they did not want them
Our release cadence is too fast. It's too easy to introduce a lousy feature into EFSA that we are now stuck with maintaining for an eternity
Stability - we do an okay job being stable, but we could do much better

Pre-Releases

We should use pre-releases as "unstable" and "experimental" releases for EFSA and EFHST. Only working group sites, which we frequently modify on a weekly basis, should be on them. (e.g. eclipse.org, eclipse.org/events, sdv.eclipse.org, jakarta.ee).

We should utilize pre-releases similar to how we currently make releases. The release cycles can be as quick as we need them to be. We could quickly add, break, and revert changes to get things done. Nothing changes other than the type of release we make - and their usage should be discouraged for the community.

Patch Releases

We should utilize these for bug fixes and security updates for a target minor or major release. If our process is airtight and our patch releases are clean, we should be able to trust Yarn to download security patches as we go. Doing so should lessen the burden of manually upgrading versions for security upgrades, a problem we've wanted to resolve for a while now.

Patch releases should be released at a faster rate than minor releases. We could cherry-pick a patch from an experimental release and release it right away.

Examples of patch releases:

Copyright footer update (maybe?)
Security patches
Fix the wrong color used in a component
Fix JS error

Minor Releases

These releases should include new, non-breaking features to the package.

A minor release is made once a feature has been added to a pre-release for a significant amount of time (minimum 2-4 months, for example). The time between releases is important—it gives us time to know whether a new feature is something we want to commit to maintaining in the long run. Otherwise, we are stuck with it until the next major release.

Users should know that these upgrades could include new features they can use. Their project should not break when upgrading to these.

If something does break, we must fix it. This breaking change should be pushed to the next major release if intentional.

Who should use minor releases? Community members or sites maintained by us web devs which do not get constant attention (e.g. AsciiDoc, openPASS, Eclipse LTS)

Examples of minor releases:

A new shortcode
A new param for config.toml
A new frontmatter param

Major Releases

These releases should include breaking changes.

We want to create a major release at a low cadence. Perhaps yearly. These will allow us to break APIs and eject from changes we no longer want to commit to.

Users should know that upgrading to one of these may break their project.

Examples of major releases:

Bootstrap 5 upgrade
Hugo or Node.js upgrade
A major redesign like Astro
Updated function signatures for functions which were externally exposed (e.g. renderTemplate)

Why are these necessary?

Breaking changes are inevitable. It is impossible to write great features that can be maintained forever on the first try, especially when the time between our releases is ~ one week. We need more time to gauge whether we wrote a feature correctly or if it is a feature we even want to keep.

Historically, we have introduced breaking changes. However, nothing in our versioning process tells a user that these breaking changes were expected or if they are bugs. Users should never experience a breaking change unless they specifically upgraded major versions.

Change Logs

We could adopt conventional commits to automatically generate changelogs and help us determine whether a release needs to be major, minor, or patch.

These can be linted by pre-commit hooks or CI/CD pipelines. Here's a list of tooling: https://www.conventionalcommits.org/en/about/

TLDR

We should use pre-releases the same way as we currently push updates for EFSA+EFHST.

We can utilize other types of releases to stabilize EFSA and EFHST, streamline processes such as patching security vulnerabilities and fixing bugs, and enhance the stability of dependent websites.