lukasbestle
commented
2 years ago Thank you for your detailed comment. We understand your frustration and we want to improve:
- We have updated the guide with an explanation on our current versioning scheme. We need the generation for licensing purposes only as every generation change would be a paid upgrade.
- We have updated the security policy with a security update guarantee for older major versions. This allows you and your clients to safely stay on older major versions for two years after the next major version was released.
- For future major releases we plan to write a detailed migration guide for all relevant breaking changes.
- We plan to include information on Kirby version support in our plugin directory to make it easier to see if a particular plugin was already updated.
- We also want to invest time to help plugin devs with updates like we intensively did with Kirby 3.6. Plugins are created by the community and supported by the community, so we cannot keep them all working just with work by the core team. But we want to focus on the most popular plugins.
There's one part we unfortunately cannot solve like you suggest:
First of all, I would suggest keeping breaking changes to a bare minimum and keep legacy stuff in the codebase if it helps to keep breaking changes to a minimum.
There are certainly different possible approaches for dealing with breaking changes. E.g. in the operating system world, there are two extremes: Microsoft carries around legacy code with parts that are decades old to keep the backwards compatibility with even ancient software. Apple cuts off support for legacy code pretty quickly and provides new APIs instead.
We develop Kirby more with the latter approach. This allows us to keep Kirby's core slim, which increases the security and reliability of the system. Of course you are right that the downside is that plugins can and will break. We unfortunately cannot optimize both for backwards compatibility and reliability at the same time. We hope that the solutions we propose above are a step in the right direction to close the gap.
PS: Sometimes it's really difficult to provide full backwards compatibility even if we wanted. That is with undocumented internal APIs that some plugins (like Pagetables) depend on. We aim to keep our official plugin extensions and developer- and user-facing methods stable. With these we first check if a breaking change is really necessary. If so, we deprecate the old behavior and only remove the legacy code in the following major version. This allows enough time to adapt. But with internal APIs, especially with our Vue components, every change can potentially be breaking and it is impossible to anticipate this. It's a difficult problem and there is unfortunately not a good solution for it. This is the same with every other software product.
Hi there!
The recent release of version 3.7 introduced – similar to previous releases – a number of breaking changes. While these are documented on the release page, they do pose a substantial issue for existing projects as those run the risk of – sometimes silently – breaking every time there is a dot release.
After having read a few comments by the Kirby team here and there about the practice, I am now under the impression that this process is unfortunately handled rather poorly and would like to open a discussion here to hopefully improve the situation.
@afbora stated in a GitHub issue regarding a now broken plugin (resulting from breaking changes in v3.7)
As I stated in my response there, I fail to see how this is not Kirby related. The Kirby team publishes a release, breaking several plugins that existing projects depend on and then leave the plugin maintainers and the project maintainers alone with this mess, even opening a new issue somewhat unhelpfully stating that the plugin is not yet 3.7 compatible, without giving any further explanation why exactly.
And this is not just any plugin that is breaking, this particular one has 112 stars on GitHub and is mentioned in the Kirby forums a lot so it could reasonably be expected to probably be integreated in hundreds, if not more, projects. Just today I discovered the next plugin that was rendered totally useless by 3.7, as documented here. And this is two plugins out of maybe 10-15 plugins that I have been dealing with since the 3.7 upgrade, which I find quite substantial.
This is a real issue, as both these plugins broke silently, without throwing any errors at all. With the second one I caught it before going live fortunately, but with the pagetables plugin I was not careful enough and deployed the Kirby update before checking the backend (and sure, this is my fault to a degree, but it also means that I have to carefully double check every single backend before I deploy a Kirby update).
To further quote myself: As it stands Kirby 3.7 totally breaks my workflow for [some] projects and I am unable to update (and even unable to set up new projects with similar requirements in 3.7). Usually, I'd expect a dot release not to break backwards compatibility, especially not for a paid product.
To which @lukasbestle responded:
I'm not really buying this. Not only is this "generation numbering" nowhere communicated, so I as a customer could not be expected to know about this somehow, but the Kirby docs themselves refer to Kirby v1, v2, v3 etc. as "versions", like on the Kirby Security Policy Page for example.
This is also where my next – and maybe main – concern comes from: if 3.6 is considered its own version as Lukas states, then I would expect that I can stay with this version indefinitely. This however is not possible, as there are no security patches for older "dot versions". As the Security Policy Page shows, there are no 3.4 patches for the high severity security issues that came to light in 3.5, so I cannot reasonably be expected to keep running my page in v3.4.
It also is a real issue to "sell" this to my clients. In theory it's possible that they pay for a Kirby licence that after a few weeks is either affected by a security issue or that has some features becoming unusable by then. This is a situation I find hard to justify towards my clients. It's never an issue to explain customers that they have to pay a one time licence fee for the backend, but it turns out that – unsurprisingly – it is an issue explaining to them that a certain feature suddenly stopped working and doesn't really increase their trust into Kirby as a product.
The problem is that I – as many other developers – might have the knowledge how to use and how to customize Kirby, but we don't have the deeper knowledge of its inner workings that would allow us to easily dig into the source code and know how to fix a plugin. Also, plugin maintainers seem – no surprise there either – notoriously busy so even if they would know how to fix a plugin they might not get around to it.
When looking at the release page and trying to track down why the plugin might be broken, I end up in the Panel section, listing these two points:
Both of these are not helpful at all. They don't state any migrations steps and leave the plugin devs or users alone with the broken stuff.
So, what might be a solution?
First of all, I would suggest keeping breaking changes to a bare minimum and keep legacy stuff in the codebase if it helps to keep breaking changes to a minimum. I know that the Kirby dev team states that breaking changes are introduced carefully, but having two of the few plugins I have recently used silently break and having no real documentation on migration steps leaves a doubt if the steps were really taken that carefully.
Then, I would like to kindly ask, to allocate some dev power for the Kirby team to step in and at least provide fixes for the more popular plugins if they are affected by a breaking change. As mentioned, plugins like pagetables have a lot of GitHub stars and find mentioning in the forums all over the place, so one could expect that they have a wide userbase. Also, after all, they are also still listed on Kirby's plugin page. I would expect plugins that are listed there to generally work and not to have spend a substantial amount of time figuring out if I am using a plugin wrong or if it became unusable due to recent breaking changes.
Thankfully, in the case of the pagetables plugin, @distantnative has done just that and provided a fix. Maybe in the future there could be a set of migration scripts that plugin maintainers could use (as has happened in the past, IIRC?) and maybe the Kirby team could provide help in taking the migration steps that goes beyond "This plugin is not 3.7 compatible".
Please do not get me wrong – although I am giving quite severe critism in this issue, I am doing this as someone that came to love Kirby and who uses it in dozens of projects and wants to keep doing so in the future. I just hope that this issue gives an insight into an end user's perspective and that there can be way to handle such changes better in the future.
Thanks for reading, looking forward to your thoughts. trych