Hello Rohit, and dev community,
I'm sorry, but I do not understand your (Rohit) position. I have
stated the reasons for my proposals and I have been waiting for the
feedback of the community (including yours).
Since it seems like you did not fully understand my proposals, I will
try to make them clearer, in hopes you can either agree or debate with
me.
There are three major points that I would like to discuss, and since
these points are intertwined, they should be discussed together.
### Breaking Changes
No one likes to have their integration broken by an API change that
broke backwards compatibility, even worse if the community did not
very clearly communicate this change. Nonetheless, CloudStack is an
evolving platform, with much development still being made; it is far
from complete. Thus, it is natural for such a platform that it will
have a few breaking changes in the future, or else it will die,
suffocated by its own cocoon (read: restrictions).
It is in this light that I would like to discuss a change to our
current policy on API changes. Currently, on the one hand, we forbid
"big" breaking changes, such as refactoring our APIs to be RESTful; on
the other hand, we allow "small" breaking changes to be made, and will
not necessarily communicate with users about it. However, I believe
that changing both policies may be beneficial for the platform as a
whole. My intention regarding breaking changes is:
- Allow bigger refactoring and introduction of breaking changes; after
being properly discussed, agreed, and communicated to the public.
- Make "small" breaking changes clear to the community; after all, any
breaking change should be properly discussed and announced, so users
are aware and ready for it.
### Database Changes
We often introduce many database schema changes in each version. It is
done in our NON-SECURITY PATCH versions, but it is always done in our
MINOR versions (here I'm using the definition given in our wiki [1]).
I see this as a problem for users that might have problems with a new
MINOR version and want to roll back after noticing a problem days or
weeks after the upgrade, but now will suffer data loss since they must
restore an old backup of the DB, as the DB might become incompatible
between versions.
I recognize that security patches that might need to change the DB
schema shall not be stopped, and **I am not proposing we block
these**, for obvious reasons. A sidenote here, I can't recall having
such a case, could someone give me a link to a security patch when
this has been already needed? If not, it seems a bit off to use this
argument.
Thus, what I am proposing is that we modify our DB change policies:
- Regarding DB **schema** changes, these should be done only in MAJOR
and SECURITY PATCH versions (only when/if needed).
- Regarding DB **data** changes, these may be done in any version.
### Feature Removal
We already have a great feature removal process. My only concern with
it is that it does not specify that feature removal must be done in a
specific type of version, and so technically it could be done even in
a SECURITY PATCH version. Thus, my proposal for it is simple:
- Specify, in the feature removal process, that a feature must be
removed in a MAJOR version. After having been announced in a previous
MAJOR or MINOR version, following the rest of the protocol already
defined.
### Version naming
I was really trying to separate this topic from the rest, as it is
simply a consequence of the other three. However, since it seems like
some really want to discuss it, I will give my opinion on it:
I think that our version naming is silly, having version 4.X.Y.Z
forever does not make sense. I think that going back into a X.Y.Z
version naming (and thus going back to semver) is much more sensible.
Thus, since I was not able to keep the community from discussing both
topics together, I will propose the following:
1. Change our version naming pattern from
<MAJOR>.<MINOR>.<NON-SECURITY PATCH>.<SECURITY PATCH> to
<MAJOR>.<MINOR>.<PATCH>.
2. Patch version MUST be incremented if **only bug fixes or security
fixes** are introduced. A bug fix is defined as an internal change
that fixes incorrect behavior. A security fix is defined as an
internal change that fixes a CVE.
3. Minor version MUST be incremented if any functionality is marked as
deprecated. It SHOULD be incremented if improvements are introduced
within the code. It MAY include patch-level changes, as well as new DB
data inserted by the system, or a new feature is introduced. Patch
version MUST be reset to 0 when minor version is incremented.
4. Major version MUST be incremented if any backward-incompatible
changes are introduced. It MAY also include minor and patch-level
changes. Patch and minor versions MUST be reset to 0 when major
version is incremented.
Note that this is very, very inspired by semver [3] but I have changed
some points to better fit the CloudStack reality and the community way
of working.
For this to work, we will have to either:
- Drop one of the numbers of our version naming;
- Start a new version naming;
I am not a fan of restarting the version naming as it could bring a
lot of confusion; thus, I would propose we drop one of the numbers of
our version naming. Regarding which number, since our current MAJOR
(the number 4) in our <MAJOR>.<MINOR>.<NON-SECURITY PATCH>.<SECURITY
PATCH> has never been changed, I would suggest we drop it, as no one
has ever used it anyway.
I propose that all of these changes take into effect after 4.21.0.0 is
released. Thus, after 4.21.0.0, the next version should be 22.0.0.
Regarding the LTS of our versions, I propose we keep it as it is
currently. That is, MAJOR versions like 22.0.0, 23.0.0, etc., would be
the LTS versions. And MINOR/PATCH versions should be used to add
backward compatible features and fix bugs, respectively, in the LTS
versions. Taking an example, 22.0.0 would be an LTS, where 20.0.x
patches would be patches on top of the LTS; on the other hand, 22.y.z
would not be an LTS. Therefore, we would not need to worry about apply
patches to all 22.y branches/versions. Patches would only need to be
maintained in the LTS, which means 22.0.x versions.
Furthermore, I know that we try our best to do this, but we should
create a policy that patches should be added to every LTS version
which is affected by the issue. And backwards compatible features
should follow the same policy. Again, no big change here, we are
already basically working like this.
Regarding the LTS of 4.21.x.x and 4.20.x.x, we shall keep it as it is,
and their version naming should remain as the old one until they are
out of LTS. All versions after 4.21.x.x will follow the
MAJOR.MINOR.PATCH version naming.
I hope this clarifies what I am going for. I am eager to hear back
from the community. If no negative feedback is given within a week of
this message I will assume lazy consensus and will start a new vote
thread with these points up to vote.
Best regards,
João Jandre
[1]:https://cwiki.apache.org/confluence/display/CLOUDSTACK/LTS
[2]:
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=68720798
[3]:https://semver.org/spec/v2.0.0.html
On 5/14/25 03:48, Rohit Yadav wrote:
I've made my position clear, if there's no scope for further
discussion I'll add my vote.
Thanks.
________________________________
From: João Jandre<j...@apache.org>
Sent: Tuesday, May 13, 2025 19:08
To:dev@cloudstack.apache.org <dev@cloudstack.apache.org>
Subject: Re: [Discussion] Versioning
Hello Rohit,
> I think we need to break out the topics and discuss them separately.
Personally I wouldn't be able to work & vote this weekend, but I can try
to participate during work days next week. We can vote again if
required, but I think voting isn't required if consensus is achieved.
These topics are intertwined, I believe that discussing them separately
will hinder the discussions. Also, as we are changing a process that has
been followed for many years, voting is an important step to formalize
the changes.
> On #1: I don't think we follow semver [1] strictly anymore. Our
versioning scheme is currently A.B.C.D (where D is for security, C is
maintenance/path; but B is considered a major release, A relates to API
backward compatibility). To give some historical context - the original
authors started with semver because they needed something to base
versioning scheme on and followed it b/w 4.0 and 4.5; then starting
security releases I think around 2016-2017 we introduced the security
patch created our own versioning scheme & DB upgrade paths mechanisms
around it. With LTS [1] guidelines adopted a few years back, we created
a way for us to support new hypervisor support delivered in
maintenance/minor releases which often have DB changes (adding guest os
mappings, capabilities etc.) and any core infra blockers. For the most
part - for marketing purposes, in events, conferences, announcements etc
we consider "A.B" as a major ACS release (for example, we say 4.21 is
the next major LTS release...), and we refer to A.B.C as a
maintenance/minor release. (for example 4.20.1.0, or 4.19.3.0).
We do not follow strictly semver, as per the link you mentioned,
however, the same link specifies that the only change is the following:
---
<MAJOR>.<MINOR>.<NON-SECURITY PATCH>.<SECURITY PATCH> where NON-SECURITY
PATCH is incremented for all bug fix releases except those addressing a
CVE. The SECURITY PATCH is only incremented for security releases that
fix one or more CVEs.
---
The rest should be semver. Also regarding the page you mentioned, it
specifies that the MAJOR would be our 4, as it is the first number;
therefore, we cannot consider "A.B" the MAJOR, as it is a MINOR. Again,
the community has not been following its own guidelines and it seems
that there are confusions regarding the versioning. **This is why we
must discuss and solidify our process**.
> My view is, it's not in our community's best interest to introduce
severely disruptive changes (APIs for example) as we've built a momentum
of users, sub-projects and sister-projects that depend on CloudStack
(APIs). So, if we can accept that there will be never a major release
(from a semver PoV) disrupting the APIs, we can drop the "4." and call
the next set of releases 22, 23 etc. forking our version of "semver"
even further. If that's the extent of the proposal, I'm supportive of
that.
> On a pedantic note, the proposed voting thread's subject is about
versioning process but it suggest that the proposer "will start another
thread regarding our version naming" - making it harder for community to
vote on something that's not well defined or proposed.
It seems that two different topics are being mixed here, on one hand we
have the versiong process, on the other we have the naming. They do go
hand in hand, but they can be discussed separately, I see that you have
an interest in changing our version naming, I do not oppose that;
however, I'm interested in the versioning process, this is what this
thread is about and why I want to create a new thread for version naming
discussion.
Regarding the disruptive changes, we have already been introducing these
types of changes, but as we have not been following a proper process,
these changes have been made to the MINOR release, and what is worse, a
lot of times users are not informed of such changes in advance.
Here are a few example of disruptive changes:
-https://github.com/apache/cloudstack/pull/9518. Changed the default
connection pool library. This was not communicated to the community and
we have caught problems caused by this change, where we had to revert to
the old library.
-https://github.com/apache/cloudstack/pull/7131. Updated the log
library. This change was announced in the MLs (see
https://lists.apache.org/thread/wnh2d0r3dyphzmc0c6rytj2mbd21z2gs) and
was explicit on release notes for example, but I still feel like we
could've communicated a bit better about the change, for example
notifying the deprecation of log4j 1.29 in the previous version. In any
case, this is a disruptive change that was not made in a MAJOR version
as defined by semver.
-https://github.com/apache/cloudstack/pull/8609. JRE Upgrade, removed
support for EL7. Again, this was communicated in the release notes, but
as far as I know we did not notify the users of the deprecation EL7 in
the previous versions.
> On #2: we already have a deprecation policy [1] which was led by
Rafael and we've used it already with quite a few deprecations; notably
the deprecation of legacy UI and introduction of the modern UI, where we
supported the legacy UI for two major releases until we removed it.
We do. But it allows removing features on minor versions; thus, it does
not follow semver.
> On #3: I don't think it's in our best interest to lose the
ability to
have DB changes (both data & schema) in maintenance/minor & security
releases. The LTS/hypervisor support is a good example and also
optimisations, critical/security issues examples we've delivered in past
maintenance releases that required DB changes (both data & schema).
The exception for security changes has already been discussed and I
agree that it should remain an option to be used when necessary.
Regarding changing the database schema in minor versions, I believe it
is in the user's best interest to have such a guarantee; this way,
upgrading/downgrading from minor versions inside the same major would
pose no issues and could be done whenever needed. I think the cost of
waiting for the next major before having a possible optimization is
worth the cost of having a stable environment. Moreover, I am not
proposing to stop DB data changes (e.g. inserting/removing/altering
something in the database to normalize some inconsistency) in minor
versions, only schema changes.
Best regards,
João Jandre
On 5/9/25 09:19, Rohit Yadav wrote:
I think we need to break out the topics and discuss them separately.
Personally I wouldn't be able to work & vote this weekend, but I can
try to participate during work days next week. We can vote again if
required, but I think voting isn't required if consensus is achieved.
On #1: I don't think we follow semver [1] strictly anymore. Our
versioning scheme is currently A.B.C.D (where D is for security, C
is maintenance/path; but B is considered a major release, A relates
to API backward compatibility). To give some historical context -
the original authors started with semver because they needed
something to base versioning scheme on and followed it b/w 4.0 and
4.5; then starting security releases I think around 2016-2017 we
introduced the security patch created our own versioning scheme & DB
upgrade paths mechanisms around it. With LTS [1] guidelines adopted
a few years back, we created a way for us to support new hypervisor
support delivered in maintenance/minor releases which often have DB
changes (adding guest os mappings, capabilities etc.) and any core
infra blockers. For the most part - for marketing purposes, in
events, conferences, announcements etc we consider "A.B" as a major
ACS release (for example, we say 4.21 is the next major LTS
release...), and we refer to A.B.C as a maintenance/minor release.
(for example 4.20.1.0, or 4.19.3.0).
My view is, it's not in our community's best interest to introduce
severely disruptive changes (APIs for example) as we've built a
momentum of users, sub-projects and sister-projects that depend on
CloudStack (APIs). So, if we can accept that there will be never a
major release (from a semver PoV) disrupting the APIs, we can drop
the "4." and call the next set of releases 22, 23 etc. forking our
version of "semver" even further. If that's the extent of the
proposal, I'm supportive of that.
On a pedantic note, the proposed voting thread's subject is about
versioning process but it suggest that the proposer "will start
another thread regarding our version naming" - making it harder for
community to vote on something that's not well defined or proposed.
On #2: we already have a deprecation policy [1] which was led by
Rafael and we've used it already with quite a few deprecations;
notably the deprecation of legacy UI and introduction of the modern
UI, where we supported the legacy UI for two major releases until we
removed it.
On #3: I don't think it's in our best interest to lose the ability
to have DB changes (both data & schema) in maintenance/minor &
security releases. The LTS/hypervisor support is a good example and
also optimisations, critical/security issues examples we've
delivered in past maintenance releases that required DB changes
(both data & schema).
[1]https://cwiki.apache.org/confluence/display/CLOUDSTACK/LTS
[2]
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=68720798
Regards.
________________________________
From: João Jandre<j...@apache.org>
Sent: Friday, May 9, 2025 00:19
To:dev@cloudstack.apache.org <dev@cloudstack.apache.org>
Subject: Re: [Discussion] Versioning
Hello, Rohit
I'm very sorry to hear that your country is at war. Do you think
that if
we extend the voting to a full week, you can participate?
Regarding your comments:
1. Semver is very specific on how the version naming should be; it
should only contain three version numbers, not four. Furthermore,
adding
breaking changes on minor versions is very much not following semver. I
would like to start using semver, but for this, we must change our
current processes and practices. This is why this thread was created.
2. Regarding the deprecation, we have a process, but it allows removing
features on minor versions; thus, it does not follow semver.
3. Regarding database changes, the proposal being voted is very clear
that there might be exceptions for security changes that necessitate
database schema changes. Regarding changing the database schema in
minor
versions, I believe it is in the user's best interest to have such a
guarantee; this way, upgrading/downgrading from minor versions inside
the same major would pose no issues to the DB. Moreover, we should not
confuse DB schema changes with DB data changes (e.g.
inserting/removing/altering something in the database to normalize some
inconsistency)
Best regards,
João Jandre
On 5/8/25 09:42, Rohit Yadav wrote:
Sorry all - I'm busy at work but want to chime in after considering
the thread (plus my country's at war atm). I need more time and I
wouldn't be able to vote within 72 hrs.
On the face value - none of the three things needs voting on, we
already use the semver & have used deprecation process for
components already, and I don't think it's in community's best
interest to lose the ability to deliver database-changes in
maintenance/minor & security releases.
Regards.
________________________________
From: João Jandre<j...@apache.org>
Sent: Wednesday, May 7, 2025 22:40
To:dev@cloudstack.apache.org <dev@cloudstack.apache.org>
Subject: Re: [Discussion] Versioning
Hi everyone,
As it seems we have no objections to the proposed changes to our
versioning, I'll be starting a voting thread to vote on the changes to
the versioning process that were discussed on this thread.
Once the first subject is decided (the process to follow and guide the
release process), I'll start another thread regarding the versioning
naming/pattern we will adopt.
Please note that I'm proposing that these changes only take effect
**after** 4.21 is released.
Best regards,
João Jandre
On 4/30/25 16:06, João Jandre 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.
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).
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.
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.).
- Database Schema: Changes to the database schema should also be
introduced only in major versions.
- 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.
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.
Regarding the next major naming (e.g., 5.0, 2025.0, 22.0, etc.) we
can
have a separate voting to decide on it.
Looking forward to your thoughts and feedback.
Best regards,
João Jandre
