(wip) Compatibility Planning

Overview

Benefits of defining Major vs Minor versions for Users

• Intuition and some structure of what might be in NEWS.txt and CHANGES.txt
• Planning Upgrade paths. e.g. it's ok to upgrade 4.0 to 4.2,  but not 4.0 to 6.0
• Expectation of when deprecated features and APIs will be removed (hard break)
• …

Benefits of defining Major vs Minor versions for Dev community

• Re-use of industry standard
• Common understanding for removal of features
• Less confused and annoyed users
• …

Benefits of defining Patch versions for Users

• Safety in upgrades.
• Reduced testing before upgrading.

Benefits of defining Patch versions for Dev community

• Reduce Committers time on reviewing by focusing development on trunk.
• Reducing complexity of forward-merging by limiting the types of patches going into release branches. 
• More users on more recent patch versions.

Patch versions

• Strictly speaking, only bugs that are non-disruptive and non-API breaking. Consensus is used to include bugs that impact existing behaviour/interfaces.
• There are lots of very minor improvements, particularly in certain parts of the code, that make sense to include. Consensus is used to include these in lieu of formal guidelines.

Versioning in Components

Areas of Compatibility

• CQL
• SSTable format
  SSTable format consists of two letters version descriptor (in ancient releases of Cassandra it was just one letter). The two letters denote major and minor version of an SSTable. The versioning is independent for each SSTable format (which will start to make sense once CEP-17 lands in). Major version change requires a new major version of Cassandra, and therefore it cannot happen in a minor release.
  Minor SSTable format must be forward compatible for any minor version change. That is, any previous minor release of Cassandra must be able to read any SSTable created by further minor release of Cassandra. For example, Cassandra 4.0 must be able to read SSTables created by Cassandra 4.1. Breaking that requirement by a new SSTable format is a justification for bumping its major version, and thus the major version of Cassandra.
  One of the frequently updated components of an SSTable is STATS. According to the above rules, it is allowed to add new fields to the statistics metadata at the end of a file because such a file still can be read by the previous minor version of Cassandra. Though, removing, modifying or changing order of fields, requires a new major version.
• Server
• …

Code Components

•  …

Non Versioned Components

• Website (top-level) documentation
• Cassandra-builds repository
• Cassandra-dtest repository

Applying Semantic Versioning

Major Changes

• Removing a deprecated feature or API
• Delimitate upgrade paths
• New major SSTable format version

Minor Changes

• New minor SSTable format version

Patch Changes

• Bug fixes
• API invisible minor improvements
• … 

Notes:

Easy java packages to compartmentialise… -- SASI, 2i, (SAI)
 -- Security and Auth
 -- Triggers
 -- Auditing and FQL
 -- Tracing and Diagnostics

Component list from 4.0 Testing…

• Components
  • ✅ Internode Messaging
  • ✅ Test Infrastructure / Automation: Diff Testing
  • ✅ System Tables and Internal Schema
  • ⏳ Source Audit and Performance Testing: Streaming
  • ⏳WIP: Test Infrastructure / Automation: "Harry"
  • ✅ Local Read/Write Path: IndexInfo (CASSANDRA-11206)
  • ⏳WIP: Local Read/Write Path: Upgrade and Diff Test
  • Local Read/Write Path: Other Areas
  • Distributed Read/Write Path: Coordination, Replication, and Read Repair
  • Repair
  • Tooling: Bundled / First-Party
  • Tooling: External Ecosystem
  • Test Frameworks, Tooling, Infrastructure / Automation
  • Cluster Setup and Maintenance
  • Cluster Upgrade
  • Documentation
• Features / Substantial Changes
  • Transient Replication

Component list from JIRA…