Throwing my two cents out… I'm keen for us to better adhere to SemVer rules (I've said this before). Specifically defining the difference between a Major and a Minor version, and defining the difference between a Minor and a Patch version (which in turn addresses your questions Josh). But this is rather tricky for us because it is a big and complex codebase and technology, one which focuses on availability at all times. The easiest way so far for me to think about this is through the eyes of the user, and the benefits we can give to them.
Some examples of benefits that come to mind… * Major versions can be used to demarcate upgrade paths, e.g. you cannot jump over a major when upgrading. * A clearer expectation of when deprecated features and APIs will be removed, e.g. removal of deprecated features and API can only happen in a Major version. * Building on the previous, give the user some structure they can follow (helping to build intuition) of what might be in NEWS.txt and CHANGES.txt. * Safety in upgrades if we are stricter about can go into a Patch version. Then it is easy to think about the knock-on benefits from this to the dev community. Clarity about what versions may contain, and what degree of testing is involved in each upgrade, will encourage users to upgrade more often, which helps us. Worth noting that this is something we are already now asking of users, with annual releases only being supported for 3 years. Where it does get tricky is, we really cannot define this by jira issue types. Improvements and Bugs can have API changes, or incur significant behavioural changes (8099 comes to mind, which was an improvement). Features can also be clean additions onto existing SPIs, marked as alpha|beta and applied safely on any past version where that SPI exists. And Improvements are quite often operational fixes (a quick scan of CHNAGES.txt for any patch release shows this). This will be easier to formulate if we better define project components and work off them. Stuff like tools and client-side stuff, packaging, tests, and SPI implementations, can be dealt with quite differently. Such a component list will also help us ensure we get adequate reviews on patches and what they touch. I've half-baked started this here: https://cwiki.apache.org/confluence/display/CASSANDRA/%28draft%29+Project+Roles+and+Responsibilities ; but am struggling to find time to progress it, any help would be appreciated. (We have the detailed component list already in jira that we can re-used here as well.) I do doubt this will be but a helping guide, where the guidelines are ultimately defined on user-centric criteria. In lieu of such guidelines in place, I am in favour of the following for restricting what can go into a Patch version: - Only bugs that are non-disruptive and non-API breaking can go in without any discussion. - Other bugs (those that impact existing behaviour/interfaces) require a consensus. - Minor improvements, particularly in safe parts of the code, or are in essence an operational fix, that make sense to include require a consensus. Consensus in all of the above is according to our Code Contributions voting as described under our Project Governance, and it can be part of the discussion on the ticket, but also raised to the ML if doubts exist. This is a very light enforcement of the rules, allowing common sense to prevail, while letting the encouragement of discussion help organically define our guidelines over time. As to what makes trunk bump up to a Major version (if it hasn't already during the current release cycle), I'm for starting with some basics like "this patch breaks upgrades from the previous major" and "this is a significant underlying change to a subsystem", and again encouraging discussion as we figure it out. Finally, to the topic of "stable trunk" and feature flags. Feature flags should absolutely be used more, and new features should come out as disabled by default (as we have been doing more of). There is also some commonality here with SPI implementations in how they can be accepted into the code. On the topic of stable trunk: this is a new journey for us and it was tried (in a way) before with tick-tock without much luck. I do believe we can get it right this time, but I am scared of applying it to anything but trunk for the next year until we can validate its success. It is only to imagine if tick-tock had been applied to all release branches, help. Stable Trunk will no doubt need some fine-tuning as we go. So, I would like to leave our release branches alone as much as possible. Furthermore, my understanding of a stable trunk is that its success will be validated by how few patch versions we release, and how quiet our release branches end up being. This will have the benefit that our (very limited) reviewing capacity can focus more on trunk. And in turn, the more eyes that focus on trunk the greater success of a stable trunk. On Thu, 26 Aug 2021 at 19:37, Joshua McKenzie <jmcken...@apache.org> wrote: > The discussion came up on > https://issues.apache.org/jira/browse/CASSANDRA-16873 concerning where > we land different diff types and it was clear the conversation should > come to the ML and the outcome be codified for the future. > > Some useful pre-reading on the Release Lifecycle on our wiki: > https://cwiki.apache.org/confluence/display/CASSANDRA/Release+Lifecycle > > For context if it's not clear in the wiki article, the three release > types we have currently: > 1. Patch: N.M.x > 2. Minor: N.x > 3. Major: N > > Currently the wiki articulates the following under General Availability: > * Incremental fixes for post-GA issues identified will be included in > patchlevel releases. > * A new branch is created for the release with the new major version, > limiting any new feature addition to the new release branch, with new > feature development will continue to happen only on trunk. > > The question that came up discussing C-16873: > What qualifies as an "Incremental fix" for purposes of inclusion in a > patch release? > * Do all bugs qualify? Only some? > * What if a bugfix breaks an API? Where does that land? > * Do small improvements that are not API mutating qualify? > * If improvements, who decides? Lazy consensus w/2 committers? > > I'm personally pretty neutral; there's a cost-benefit to this and no > clear optimal answer to me at face value. > > Lastly, I also advocate for a clear definition of expectations on > these releases in the wiki, something like: > > Major: API changes, feature deprecation, protocol changes > Minor: New features, changes in default behavior > Patches: Whatever we decide in this thread > > What do we think? > > ~Josh >
