LemmyNet
Stability Guarantees for Lemmy 1.0
The release of version 1.0 will be a good opportunity to formalize the stability guarantees we give to instance admins and client developers. This will give them confidence to rely on Lemmy in the long term.
The last breaking change was with 0.19 released two years ago. For 1.x it should be realistic to maintain it for 5 years after the initial release. This means a client that works with 1.0.0 also works with the latest 1.x version released 5 years later. And bug/security fixes will be backported for that time, even if a version 2.0 were released before the 5 years are over. Similarly we can maintain minor versions (1.0, 1.1, 1.2 etc) for 2 years after release, even if a new minor version is released within this time. However keep in mind that more maintenance work on older versions means less time to develop new features.
The stability guarantee covers the following:
- API
- Configuration format
- Command line parameters
- Federation
- lemmy-ansible (cc @codyro @ticoombs)
- RSS feed urls
- lemmy-js-client (including struct names)
Not covered are:
- Unstable api endpoints (https://github.com/LemmyNet/lemmy/issues/5945)
- lemmy-ui
- Specific format of RSS feeds
- Anything else outside the lemmy backend
It would also be good to know how similar projects handle this. If you know any examples please link them below.
Once decided this info should be added to 1.0 release notes and documentation.
We could also try to make guarantees that new features are under a new unstable API route: #5945 , although since new features aren't breaking, then this might not apply here.
The one place where this is difficult, is when we change the underlying DB objects. Oftentimes its not easy, and it leaves too many kludges in the code to try to make them backward compatible. But we can also be sure to use semver properly now, and make sure if there are major breaking changes, to use 2.0, etc.
We could also try to make guarantees that new features are under a new unstable API route: https://github.com/LemmyNet/lemmy/issues/5945 , although since new features aren't breaking, then this might not apply here.
This is useful in some cases where the feature is experimental and may get a different api later, or even get removed. Added it to the list. In general new features can be added to the stable api directly like we are doing now.
The one place where this is difficult, is when we change the underlying DB objects. Oftentimes its not easy, and it leaves too many kludges in the code to try to make them backward compatible. But we can also be sure to use semver properly now, and make sure if there are major breaking changes, to use 2.0, etc.
For 1.x versions we have to add these kludges, thats the price for stability. Then for 2.0 we can clean it all up just like we are doing before 1.0.
Similarly we can maintain minor versions (1.0, 1.1, 1.2 etc) for 2 years after release,
This might be a lot of work depending on how many minor releases you do.
This means a client that works with 1.0.0 also works with the latest 1.x version released 5 years later.
5 years is long time, we'll see
And bug/security fixes will be backported for that time, even if a version 2.0 were released before the 5 years are over.
For clients, less frequent major (breaking) releases is preferable.
for api stability, i recently came a cross github's api versioning garantees: https://docs.github.com/en/rest/about-the-rest-api/api-versions
this seems like a good idea to codify something similar for lemmy as well to ensure backwards compatibility.
although the last breaking change was officially in 0.19.0, at least the removal of post_id from MarkPostAsRead in 0.19.4 was a backwards incompatible api change on v3 after 0.19.0.
I like their breaking changes type list, but IMO we should just try to stick to semver after 1.0.0, and just consider any removals or changes of existing fields a breaking change. And remove kludges only after major releases.
just consider any removals or changes of existing fields a breaking change
If it's as simple as that and documented that way that would be what I was suggesting, but for example adding new required fields would not be covered by that simplified description.
Yes definitely semantic versioning. That means an api client that works with version 1.0.0 should also work with any subsequent 1.x version (eg 1.9.5) without any changes to the client.
However semantic versioning alone is not enough, because you could release 1.0 today and then 2.0 a month later, without providing further updates for 1.x. Thats obviously not what we are going to do. It may also not be obvious which parts of the project are covered by semantic versioning. For example some scripts may depend on the exact format of RSS feeds, and break if a field is added or removed. Or some browser plugins may depend on the specific HTML generated by lemmy-ui. These are things we cannot guarantee to remain stable, and should communicate it clearly.