Cassandra 4.0.x porting playbook

This is a practical sequence for moving Elassandra-specific Cassandra changes from the 3.11.9 legacy line toward Apache Cassandra 4.0.x. It complements Cassandra fork inventory (legacy 3.11 line to Apache 4.0.x).

Prerequisites

  • server/cassandra submodule checked out (same commit as cassandra= in buildSrc/version.properties).

  • Java 11 for Cassandra 4.0 builds (see Apache Cassandra 4.0 release notes).

  • Enough disk for a second Cassandra tree (clone or worktree).

Step 1 — Export patch series (3.11 delta)

From the Elassandra repository root:

./scripts/export-cassandra-elassandra-patches.sh

This adds an apache remote inside server/cassandra if needed, fetches tag cassandra-3.11.9, computes the merge-base with HEAD, and writes git format-patch files under build/cassandra-elassandra-patches/ (gitignored).

Step 2 — Bootstrap Apache 4.0 tree

./scripts/bootstrap-cassandra-40-worktree.sh

Defaults clone Apache Cassandra at tag cassandra-4.0.20 into ../cassandra-4.0-elassandra and creates branch cassandra-4.0.x-elassandra. Override with:

  • CASSANDRA_40_CLONE_DIR — destination path

  • CASSANDRA_APACHE_TAG — e.g. cassandra-4.0.20

  • CASSANDRA_40_BRANCH — local branch name

Step 3 — Apply patches on 4.0

cd ../cassandra-4.0-elassandra   # or your CASSANDRA_40_CLONE_DIR
git am --3way /path/to/elassandra/build/cassandra-elassandra-patches/*.patch

Patch 0001 (CASSANDRA-12837, multi-threaded rebuild_index) does not apply cleanly with git am on 4.0 because the index builder stack changed. An equivalent port is maintained on branch cassandra-4.0.x-elassandra in a local clone (commit message Elassandra: port CASSANDRA-12837…). Reuse or cherry-pick that commit before applying patches 0002 onward, or continue manual porting.

Patch series status (``cassandra-4.0.20`` branch, local clone):

  • Applied (with porting / conflict resolution): 0002, 0003, 0005, 0006, 0008, 0009, 0010, 0011, 0015, 0023 (schema TableAttributes + EXTENSIONS only; legacy ColumnFamilyStoreCQLHelper paths dropped), 0025, 0029 (kept 4.0 logback ReconfigureOnChangeTask handling), 0030, 0033 (NAME_LENGTH via cassandra.max_name_length on org.apache.cassandra.schema.SchemaConstants), 0035, 0036.

  • Skipped as redundant / obsolete: 0004 (concurrent type interning already in 4.0), 0007, 0012, 0013 (legacy branding / coordinates), 0014, 0020, 0021 (upstream cqlsh doc URL preferred), 0026, 0031, 0032 (git am could not build a 3-way ancestor for build.xml / CassandraDaemon), 0034 (SSL context cache: heavy merge with 4.0 EncryptionOptions).

  • Skipped pending full manual port: 0016, 0017, 0018 (full diff not applied; see below), 0019, 0022, 0024 (old config/ + service/MigrationManager / statement classes removed in 4.0), 0027 (async index build; overlaps 0018), 0028 (README).

  • Follow-up commits on the fork: Index.delayInitializationTask(); SecondaryIndexManager skips startIndexInitialization when that method returns true and exposes initIndex(Index) so Elassandra can run getInitializationTask() after shards/cluster are ready (core behavior from 0018, without the full SIM refactor). The same initIndex / startIndexInitialization split is also carried on the 3.11 server/cassandra submodule so ElasticSecondaryIndex can call one API before and after the 4.0 submodule bump. 0006 transform uses ${build.dir.lib} globs and _main-jar depends="transform".

Deferred manual ports (not yet replayed as-is on 4.0): patches 0016–0024, 0018 (full SecondaryIndexManager state machine), 0034 (SSL context cache), and related schema/migration hooks — require hand porting onto the current 4.0 packages (see Cassandra fork inventory (legacy 3.11 line to Apache 4.0.x)). The incloudsio/cassandra branch cassandra-4.0.x-elassandra carries the Elassandra-specific commits that did apply; coordinate remaining items with the OpenSearch port in the main Elassandra repo.

Almost every patch may conflict or fail to compile on 4.0. Resolve in order:

  1. Secondary index / Index SPI / SecondaryIndexManager (highest risk).

  2. CQL schema extensions and metadata transactions.

  3. Gossip / messaging / ElassandraDaemon hooks (paths moved between 3.11 and 4.0).

  4. Build system (Apache 4.0 may prefer Maven for main build; align with upstream layout).

Use git am --abort if a patch series is unrecoverable; switch to manual cherry-pick of the commits listed in Cassandra fork inventory (legacy 3.11 line to Apache 4.0.x).

Step 4 — Publish fork and submodule

When the 4.0 tree builds and tests pass:

  1. Push your fork (e.g. https://github.com/incloudsio/cassandra) on branch cassandra-4.0.x-elassandra (and cassandra-3.11.9-elassandra for the 3.11 line).

  2. Point Elassandra’s .gitmodules server/cassandra URL at that fork and update the submodule SHA.

  3. Update buildSrc/version.properties cassandra= to match build.xml base.version in the new submodule.

  4. Run ./scripts/check-cassandra-submodule.sh before release.

  5. Ensure Ant/Maven artifacts use groupId io.inclouds.cassandra (see server/cassandra/build.xml), matching Gradle dependencies such as libs/x-content — required for a coherent publish/install story.

Step 5 — Elassandra JVM integration

After cassandra-all publishes with the new coordinates, rebuild this repo and fix ElasticSecondaryIndex / ElassandraDaemon against any 4.0 API changes (often in parallel with the OpenSearch port — see OpenSearch 1.3.x porting guide (codebase map)).