Define breaking changes (according to semantic versioning) #124

oliverpool commented 2024年05月10日 11:48:32 +02:00

Forgejo publicly uses semantic versioning since v7.0.0.

However no formal definition has been made for MAJOR, MINOR, PATCH. I would propose the following:

PATCH:

• only backward compatible bug fixes (migrations should be avoided as much as possible)
• template/styling changes are possible (no guarantee for now)

MINOR:

• migrations are fine
• no feature removal
• URL changes are Ok outside of the API, as long as GET endpoints have a proper redirection (for bookmarks/history)
• API must stay compatible (additions of fields to responses or new API routes are fine for instance)
• New configurations are fine, as long as old config is still supported and no value is needed (sensible default)
• Deprecation messages are ok
• template/styling changes are fine (no guarantee for now)

MAJOR: anything else

• feature removal
• API schema change
• Configuration change

Note: template and styling customizations are currently not covered by this semantic versioning and may break anytime.

---

Ideally I think it would be great if major version would only have some feature removal, API schema changes and configuration changes.
Put in other words, every effort should be made to integrate the new features in a backward-compatible way.
This way all admins can upgrade to the latest minor version (9.99 for instance), check all deprecation messages and fix them, and the upgrade to 10.0 is mostly a no-op (from the user point of view - the sysadmin may need to adjust some tools/config files which could not be made backward compatible).

---

answered question: what about template/styling changes?̛

They will be breaking IF the sysadmin made some customization.

I would rather have the template changes under MINOR (so no compatibility-promise), at least until a clear direction has been made in forgejo/discussions#160.

Forgejo publicly uses [semantic versioning](https://semver.org/spec/v2.0.0.html) since [v7.0.0](https://forgejo.org/2024-04-release-v7-0/#70-long-term-support-lts-and-semantic-versioning). However no formal definition has been made for MAJOR, MINOR, PATCH. I would propose the following: PATCH: - only backward compatible bug fixes (migrations should be avoided as much as possible) - template/styling changes are possible (no guarantee for now) MINOR: - migrations are fine - no feature removal - URL changes are Ok outside of the API, as long as GET endpoints have a proper redirection (for bookmarks/history) - API must stay compatible (additions of fields to responses or new API routes are fine for instance) - New configurations are fine, as long as old config is still supported and no value is needed (sensible default) - Deprecation messages are ok - template/styling changes are fine (no guarantee for now) MAJOR: anything else - feature removal - API schema change - Configuration change Note: template and styling customizations are currently not covered by this semantic versioning and may break anytime. --- Ideally I think it would be great if major version would only have some feature removal, API schema changes and configuration changes. Put in other words, every effort should be made to integrate the new features in a backward-compatible way. This way all admins can upgrade to the latest minor version (9.99 for instance), check all deprecation messages and fix them, and the upgrade to 10.0 is mostly a no-op (from the user point of view - the sysadmin may need to adjust some tools/config files which could not be made backward compatible). --- <details><summary>answered question: what about template/styling changes?̛</summary> They will be breaking IF the sysadmin made some customization. I would rather have the template changes under MINOR (so no compatibility-promise), at least until a clear direction has been made in forgejo/discussions#160. </details>

KaKi87 commented 2024年05月10日 16:20:59 +02:00

Forgejo uses semantic versioning since v7.0.0.

It only displays it since then, but it's been used since earlier.

no formal definition has been made for MAJOR, MINOR, PATCH

What about forgejo/forgejo#207 ?

migrations should be avoided

Not excluded, though.

URL changes are Ok (outside of the API)

Not really, since this breaks history and bookmarks.

what about template/styling changes?

@earl-warren said at forgejo-contrib/delightful-forgejo#69 (comment) : Forgejo explicitly does not provide any kind of guarantee regarding the CSS/JavaScript/Templates: they are an internal detail, while also linking to Interface customization | Forgejo – Beyond coding. We forge. which says serving custom public files or modifying pages shown by Forgejo [...] impose an additional maintenance burden on administrators and, most importantly, are unsupported [which] means that future updates are likely to break your changes without any warning.

> Forgejo uses semantic versioning since v7.0.0. It only displays it since then, but it's been used since earlier. > no formal definition has been made for MAJOR, MINOR, PATCH What about forgejo/forgejo#207 ? > migrations should be avoided Not excluded, though. > URL changes are Ok (outside of the API) Not really, since this breaks history and bookmarks. > what about template/styling changes? @earl-warren said at https://codeberg.org/forgejo-contrib/delightful-forgejo/issues/69#issuecomment-1760642 : *Forgejo explicitly does not provide any kind of guarantee regarding the CSS/JavaScript/Templates: they are an internal detail*, while also linking to [Interface customization | Forgejo – Beyond coding. We forge.](https://forgejo.org/docs/v1.21/admin/customization/) which says *serving custom public files or modifying pages shown by Forgejo [...] impose an additional maintenance burden on administrators and, most importantly, are unsupported [which] means that future updates are likely to break your changes without any warning*.

earl-warren commented 2024年05月10日 17:12:25 +02:00

URL changes are Ok (outside of the API)

And outside of user visible URls, which leaves the web endpoints used internally but not user visible.

Open question: what about template/styling changes?
They will be breaking IF the sysadmin made some customization.

I would rather have the template changes under MINOR (so no compatibility-promise), at least until a clear direction has been made in forgejo/discussions#160.

As @KaKi87 Forgejo did not provide any kind of guarantee so far (nor did Gitea). Although blindly cherry-picking template/CSS/JavaScript changes from Gitea greatly reduced in the past weeks and since the hard fork, there still is a consensus that cherry-picking from Gitea is tolerated even when it introduces non backward compatible in the interface and is untested.

I would be inclined to not consider templates/CSS/JavaScript changes to have an impact on semantic versioning for now. It is likely to change in the future, when and if a UI team takes the lead, as a conclusion to forgejo/discussions#160 or at a later time.

The Forgejo UI/UX has not changed in years, as explained in this other discussion forgejo/discussions#151 and there is no urgency it making it happen within the next weeks or months even.

> URL changes are Ok (outside of the API) And outside of user visible URls, which leaves the web endpoints used internally but not user visible. > Open question: what about template/styling changes? > They will be breaking IF the sysadmin made some customization. > > I would rather have the template changes under MINOR (so no compatibility-promise), at least until a clear direction has been made in forgejo/discussions#160. As @KaKi87 Forgejo did not provide any kind of guarantee so far (nor did Gitea). Although blindly cherry-picking template/CSS/JavaScript changes from Gitea greatly reduced in the past weeks and since the hard fork, there still is a consensus that cherry-picking from Gitea is tolerated even when it introduces non backward compatible in the interface and is untested. I would be inclined to not consider templates/CSS/JavaScript changes to have an impact on semantic versioning for now. It is likely to change in the future, when and if a UI team takes the lead, as a conclusion to https://codeberg.org/forgejo/discussions/issues/160 or at a later time. The Forgejo UI/UX has not changed in years, as explained in this other discussion https://codeberg.org/forgejo/discussions/issues/151 and there is no urgency it making it happen within the next weeks or months even.

oliverpool commented 2024年05月13日 12:05:03 +02:00

What about forgejo/forgejo#207 ?

Thank you for pointing it out! If I read it correctly, it is more about introducing SemVer, than defining patch/minor/major. In any case I think this should be documented somewhere on the website as well (not only in an issue).

Not really, since this breaks history and bookmarks.

I overlooked that, you are right. I would propose: URL changes are Ok outside of the API, as long as GET endpoints have a proper redirection (for bookmarks/history)

what about template/styling changes?

I added the following note: Note: template and styling customizations are currently not covered by this semantic versioning and may break anytime.

> What about forgejo/forgejo#207 ? Thank you for pointing it out! If I read it correctly, it is more about introducing SemVer, than defining patch/minor/major. In any case I think this should be documented somewhere on the website as well (not only in an issue). > Not really, since this breaks history and bookmarks. I overlooked that, you are right. I would propose: `URL changes are Ok outside of the API, as long as GET endpoints have a proper redirection (for bookmarks/history)` > what about template/styling changes? I added the following note: `Note: template and styling customizations are currently not covered by this semantic versioning and may break anytime.`

earl-warren commented 2024年06月07日 23:40:08 +02:00

As 8.0.0 is approaching, it would be useful to have that agreed upon. It is a major release which makes it easy. But the next one could be a minor release and this will come handy to sort out the edge cases.

As 8.0.0 is approaching, it would be useful to have that agreed upon. It is a major release which makes it easy. But the next one could be a minor release and this will come handy to sort out the edge cases.

earl-warren commented 2024年07月24日 13:45:13 +02:00

There has been a breach in the semantic versioning logic because of a license problem. v7.0.6 is an upgrade from v7.0.5 and has a breaking change. It cannot be v8.0.0 for obvious reasons (v8.0.0 branch is already cut). These are exceptional circumstances and unlikely to happen ever again. And the breaking change does not impact anything but the User eXperience: it is in the web ui alone.

Still a remarkable exception and worth mentioning here.

There has been a breach in the semantic versioning logic because of a license problem. v7.0.6 is an upgrade from v7.0.5 and has a breaking change. It cannot be v8.0.0 for obvious reasons (v8.0.0 branch is already cut). These are exceptional circumstances and unlikely to happen ever again. And the breaking change does not impact anything but the User eXperience: it is in the web ui alone. Still a remarkable exception and worth mentioning here.

earl-warren commented 2025年01月17日 10:37:10 +01:00

Closing as it has not seen any activity in over six month and there has been no confusion or misunderstanding related to the definition of a breaking change in a year and four major releases.

It could be re-open when and if a problem surfaces as it contains a really good description of what an agreement would require.

Closing as it has not seen any activity in over six month and there has been no confusion or misunderstanding related to the definition of a breaking change in a year and four major releases. It could be re-open when and if a problem surfaces as it contains a really good description of what an agreement would require.