So to attempt to distill a set of heuristics from the discussion: Patch release: Goal: maintain and improve stability - Non-disruptive, non-API changing bugs are fine w/out consensus - Bugs that change defaults or interfaces require consensus - Improvements of any kind require consensus and must be small, in safe areas, non default changing
Minor release: Goal: stable introduction of new features - New features, always with feature flag (added; happy to drop if controversial) - No API breaking changes; additive API changes w/sane defaults acceptable Major release: Goal: provide avenue to make breaking, non-backwards compatible evolutionary changes - API breaking changes - Deprecating functionality - Changing default behaviors - Destructive / removing changes (params, features, etc) - Major, well-tested and well documented component refactors (added; happy to drop if controversial) With the above structure, we may go from Major to patches to Major without a Minor, or go from Minor to patches for awhile to Minors if we don't have destructive changes. Is that consistent w/what you're saying above Mick? If so - what do others think? ~Josh On Thu, Aug 26, 2021 at 3:37 PM Mick Semb Wever <m...@apache.org> wrote: > 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 > > >
