João, On Wed, Apr 30, 2025 at 9:06 PM João Jandre <j...@apache.org> wrote: > > Hi everyone, > > I would like to revisit the topic of versioning, particularly in light > of our last discussion (see > https://lists.apache.org/thread/hnzp6hnsjyj8593cf6tbgryt1s8z5glq). It > seems that most people here agree with the idea of transitioning to a > new major version (e.g., from 4.x to 5.0), or at the very least, are not > opposed to it.
agreed > However, I believe there are still some misunderstandings about the > reasoning behind major version changes. The number itself is not that > important; the key point is to establish a clear system for introducing > changes that break backwards compatibility. As René pointed out, we > currently do not have a formal mechanism for handling such changes. As a > result, we frequently introduce breaking changes in minor releases, > which means operators need to be aware that upgrading to a new minor > version could potentially disrupt compatibility and make their lives > more difficult when they need to roll back to a previous release after > an upgrade (e.g. if a rollback is needed after a few days of an upgrade). The biggest reasons lately people have had to roll back afaics were unforseen side effects of enhancements, not interface changes. That doesn't negate the importance of being careful with breaking changes, but as the one exception I think we must allow for breaking changes if these mitigate security issues. > > A formal versioning strategy (defining what constitutes a major, minor, > patch, and security release) would help improve the project’s stability. > It would also allow us to plan major changes more effectively and > communicate them clearly to the community. > I am aware that there has been some hesitation about establishing a > release schedule. To avoid further complications, I won’t suggest one > here, at least not until we have automated the release process. > > With that in mind, I propose that we start adhering to the semantic > versioning (semver) system that we have outlined in our documentation > (https://cwiki.apache.org/confluence/display/CLOUDSTACK/LTS and > https://cwiki.apache.org/confluence/display/CLOUDSTACK/Release+principles+for+Apache+CloudStack+4.6+and+up). > According to our current definitions, we have not had a true major > release in over 10 years, even though we have introduced breaking > changes in multiple minor releases during that time. That is one way of looking at it. Another one is regarding the 4 as mute and considering the current minor version (20) as being the actual major version currently. I say this to instill the feeling in us all that the changes to our process won't actually be that big. > To align with semantic versioning, I suggest the following changes to > our versioning practices: > - API Changes: Any changes to APIs that break backwards compatibility > should only be made in major versions (e.g., 5.x.x, 6.x.x, etc.). I'd call them 21.x.y, 22.x.y, etc (as opposed to 4.21.x.y, 4.22.x.y) > - Database Schema: Changes to the database schema should also be > introduced only in major versions. agreed > - Feature Removal: We need to update the process of feature removal (see > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=68720798) > to ensure that features are only removed in major versions, after having > been announced in advance in a previous major version. I want to amend that to say that the deprecation can be initiated in any previous version that is more then 6 months before. I don't see the need to deprecate in majort versions, only the actual removal should be. > If everyone agrees with this approach, we can begin following semantic > versioning after the release of 4.21. This means we would elect a > Release Manager for the next major as soon as 4.21 is out. If no one is > interested in being the RM for the next major, I'll put myself forward > to do it. Moreover, I would propose at least one major release per year, > and I (and the folks on our side here) would be willing to put the > effort into being the RM for these releases if needed. If I recall correctly we already had two candidates, but I am fine with whomever. > > Regarding the next major naming (e.g., 5.0, 2025.0, 22.0, etc.) we can > have a separate voting to decide on it. I think this is purely a marketing choice, with only the technical requirement that the number is above 4. > Looking forward to your thoughts and feedback. I almost agree ;) > > Best regards, > João Jandre cheers -- Daan
