Define a release schedule for the project

[JoaoJandre]

Hi all,

I had created a thread for this on the dev mailing list, but following @DaanHoogland 's advice I've decided to create a new one here. That being said, I have a proposal for the versioning scheme. Instead of dropping the "X"
on our X.Y.Z.N, we can set a fixed schedule (that can be further discussed) for the version changes:

• Every two years, we release a major version (X), which can contain changes that break backward compatibility, such as (but not limited to): removing unused/useless APIs, renaming APIs, and changing the default behavior of features. These changes must be discussed with the devs and be properly communicated to the community (via API deprecation, for example) at least one minor version before the major release;
• Every semester, we release a minor version (Y) of the current major (X) version, these can contain new features/APIs, as long as the backward compatibility is maintained; also, feature/API deprecation should happen on these versions;
• Every 2/3 months, we release patch versions (Z), that fix any bugs that were released with the major and minor versions, these versions should not contain any new features;
• In extreme cases (such as with security issues) we work on and release
  security versions (N);

The proposed schedule is only a sketch that can be worked on. However I believe that the project can benefit from:

1. A fixed release schedule;
2. A mechanism to introduce disruptive changes, so that the project can evolve and not be chained to the same features/API/limitation/technical debts forever.

Furthermore, having a schedule allows us to have a project roadmap, that outlines the future deprecations, changes and big features.

[GutoVeronezi]

Hello guys,

Thanks @JoaoJandre for raising the discussion. Many might understand the benefits and the necessity of having a well-defined versioning schema; however, I feel that it is important to highlight the "why" before discussing the "how".

We (the community) have a culture of generating code without breaking compatibility. At first look, this may seem interesting as there is an intention to guarantee the continuity of the ecosystem. However, along with that, there is also a tie with old and deprecated procedures, technologies, libraries, and models, which, in the long term, will also deprecate CloudStack and make it more costly to innovate and evolve.

We have to understand that we have several development barriers. We are already working with a highly complex context; to work with CloudStack, developers need to understand storage, networking, virtualization, Internet protocols, and much more. On top of that we do not use mainstream/standardized frameworks for the RESTful APIs and JPA; we use Spring in a non-standard fashion; we do not have a solid standard between our APIs, and so on. We are constantly increasing the complexity to extend/evolve and maintain ACS.

That creates a bubble of development where it is hard to join, which is not healthy for a community. All those development fronts mentioned require a lot of effort and investment to get addressed and will certainly generate incompatibility at some point. However, we do not have a well-defined protocol to address incompatibilities nor to release new versions; we have been on version 4 since 2012 and our minor release cadence has been sporadic since then.

Knowing that a lot of effort and investment is required to make CloudStack compliant with new and modern standards and frameworks, and our versioning schema is not foreseeable nor addresses introducing incompatibilities between versions, would a contributor or company feel safe to sponsor and put efforts into such changes?

Unfortunately, the answer is no. With that being said, by structuring a versioning schema, we can provide previsibility for the project and the community. We would know when to introduce breaking changes, and the community would be expecting them. Furthermore, we can look at how other projects, like OpenStack and GitLab, introduce breaking changes in two steps (deprecation on one major release and removal on another) to reduce their impact on the community. Moreover, we already had a discussion in the past about the same topic; thus, I invite you to check that discussion too: https://lists.apache.org/thread/lwlxs8xgz4glocctf7dv89k5nqqsxmlb

[DaanHoogland]

@GutoVeronezi points to the more abstract reasons we want to allow breaking changes.
We have long had a list of more mondain reasons to introduce breaking changes:

• API truly restful
• ORM/DAOs upgradable per feature PR instead of per version
• agent API more consistent with state of the art json frameworks.
• ...
  and the discussion will coming back. (thanks for pointing to one of the threads that highlighted this @GutoVeronezi )

On one hand, I think some of these can be introduced without breaking as well. APIs can be running alongside of each other and be slowly phased out.
On the other hand, I'd love to have the luxury to break stuff and rebuild it, but works needs to get done. The custom DAO framework we maintain will be a pain to get rid of.

As to @JoaoJandre 's proposal:

• A fixed release schedule; I think this is not feasible in a volunteer based project. Company priorities will get in the way. We can however set a guideline for LTS branches that for instance 10+ PRs/fixes warrant a release (we now do 200+ usually, so just being arbitrary)
• A mechanism to introduce disruptive changes; Yes, we should allow for that and help users on a consultancy basis if they want to migrate.

(still think we should drop the 4 yesterday)

[JoaoJandre]

@DaanHoogland, about the points you raised:

• We have examples of fixed release schedules on volunteer based projects. I think that a great example is OpenStack (see https://releases.openstack.org/), which has a major release each 6 months. Compared to that, I think that the schedule I proposed is quite tame, with majors every two years only. The biggest thing we would have to get used to is features not getting into their intended release every time: if the feature is not ready and it's time for a new release… too bad, we leave it for the next one.
• Do you have a proposal for a mechanism to introduce disruptive changes? It seems like we all agree that it should exist, but no one wants to suggest one. I think that the natural solution would be to start following the semantic versioning that our project supposedly uses.

[DaanHoogland]

I like the last sentence of your first point. We still have a 2 releases per year policy though we never make that.

As for the second point I think we should reduce out version to a 3 number scheme (still drop the 4) and allow any changes on the basis of this. However, we should still allow deprecation periods for dropping backwards compatible components or structures. And always provide well tested migration paths.