> Before going further, do we broadly agree on these 2 goals? Yes
> On Aug 19, 2026, at 7:37 AM, Josh McKenzie <[email protected]> wrote: > > Trying to distill to 1st principles here - we have a few things to optimize > for or make decisions on. Each of the following 3 have identical affordances > between a separate cassandra-utils vs. lib published from C*: > Who can depend on the code. This is priority target #1; both fix. > Who breaks when the code changes. Right now it's everyone but C*. Either > basic semver or per-API versioning fix this. > When integration happens. C* is pre-merge, everyone else is at time of > integration. > The knobs we can tune as I see it are: > Do we decouple API changes and bugfix availability? I say yes. This requires > either one branch w/per-API versioning (as proposed in CEP), or semver utils > where we only do breaking API changes on MAJOR. > When does that integration break surface? Status quo == lazy at integration > time. Alternative would be CI targets wherever utils lives to surface breaks > immediately. > Some more observations / axioms: > Any combination of approaches (cassandra-utils vs. lib, versioned APIs vs. > non) will be a strict improvement on copy-pasted duplicated code. > Any approach w/out API versioning couples bugfix adoption w/API integration. > Any versioned API approach pushes that friction upstream to people working on > the shared utils to keep that separate, whether due to annotation-based > versioning or maintaining multiple branches. > > I think it's reasonable for us to target removing duplicated code and > decoupling bug-fix integration in this shared code from API surface area > change adoption. Before going further, do we broadly agree on these 2 goals? > > > On Wed, Aug 19, 2026, at 4:29 AM, Štefan Miklošovič wrote: >> I am not against the annotation as such but I think that we are trying >> to do a lot of things at once. Just move the code over to utils, make >> it 0.1.x, wait until it stabilizes, see what has a tendency to break / >> change a lot and _then_ annotate if we still find it necessary to do >> so. If you asked me "what to annotate with what" right now I would not >> be able to say. >> >> I just prefer to move things progressively and not put annotations >> into something we will be obliged to live with from day one without >> gathering some evidence first if it is even really necessary and what >> would that look like in practice etc ... Maybe we realize that, in >> utils, just living with Semver and not having annotations at all is >> actually good enough, but I just do not know right now. >> >> On Wed, Aug 19, 2026 at 2:30 AM Yifan Cai <[email protected] >> <mailto:[email protected]>> wrote: >> > >> > Sharing my 2 cents. >> > >> > If we want the utils library to provide stable APIs from the start, >> > deferring the annotation decision isn't deferring anything — it's deciding >> > for public-by-default. >> > >> > If we want to preserve the flexibility of making breaking changes (since >> > the version is 0.x), I'm good with deferring and getting things moving. >> > >> > Honestly, from the ecosystem projects' perspective — not just Cassandra, >> > but also the projects under the same Cassandra umbrella — having the API >> > lifecycle annotated makes life easier for both consumers and maintainers. >> > That said, I am not going to die on this hill. >> > >> > - Yifan >> > >> > On Tue, Aug 18, 2026 at 2:45 PM Štefan Miklošovič <[email protected] >> > <mailto:[email protected]>> wrote: >> >> >> >> I feel like we are trying to solve everything at once. I think that >> >> extracting the utility code outside of Cassandra is already enough to >> >> deal with for now. That extraction might be a bit tricky, especially >> >> if it depends on some 3rd party library etc ... If it is really only >> >> about the candidates put into examples in the Scope section of the >> >> CEP, the dependencies should be minimal. We should strive for utils >> >> depending on the minimum of dependencies because as soon as it is >> >> going to be used in another project which is itself depending on other >> >> stuff there might be conflicts etc ... If utils is "pure Java" or >> >> close enough to that then this problem is minimized. >> >> >> >> I would leave the discussion about annotation public / private etc. >> >> for another time / outside of this CEP. In utils, for starters I would >> >> just follow Semver (non-event for patch releases, code change on the >> >> consumer side for minor releases) and leave annotations in Cassandra >> >> out of this. >> >> >> >> On Tue, Aug 18, 2026 at 11:00 PM David Capwell <[email protected] >> >> <mailto:[email protected]>> wrote: >> >> > >> >> > Thanks for the reply Francisco! >> >> > >> >> > > Instead, I was thinking that producing an artifact with utils >> >> > > as part of the Cassandra release process is probably a >> >> > > more sustainable approach. >> >> > >> >> > The main utility that has caused this debate are the test utilities >> >> > which we do not publish as part of the cassandra release. Cassandra >> >> > also only releases every 1-2 years so being able to pick up changes to >> >> > these test utilize (including bug fixes) would have to follow that same >> >> > timeline, making it harder to depend on; this was the motivating reason >> >> > for extracting outside of Cassandra. >> >> > >> >> > >> >> > > On Aug 18, 2026, at 1:17 PM, Francisco Guerrero <[email protected] >> >> > > <mailto:[email protected]>> wrote: >> >> > > >> >> > > I'm not convinced having utils in an external repo will >> >> > > be a good idea. We already have problems with >> >> > > Analytics/Sidecar repositories and you've been helping >> >> > > with the effort of consolidating those repos. >> >> > > >> >> > > Instead, I was thinking that producing an artifact with utils >> >> > > as part of the Cassandra release process is probably a >> >> > > more sustainable approach. I would expect the classes in >> >> > > this artifact will be mostly stable and don't expect many >> >> > > changes. Ecosystem projects can consume the released >> >> > > utils artifact. >> >> > > >> >> > > On 2026/08/18 14:05:05 Josh McKenzie wrote: >> >> > >>> We just make sure the builds don't break. >> >> > >> To ensure builds don't break across all projects using utils, we'd >> >> > >> need to integrate a basic build of all GA supported branches of >> >> > >> Cassandra and all ecosystem projects as a CI gate for the >> >> > >> cassandra-utils project. That would foist needing to fix all >> >> > >> dependents up to the workflow of committing an API breaking change, >> >> > >> onto the person making the change to utils or onto the delegates >> >> > >> they find at that time. This is predicated on the "one branch to >> >> > >> rule them all" model though. >> >> > >> >> >> > >> The alternative (existing API endpoints are static but you can add >> >> > >> new ones) decouples that need to update all dependents to whenever >> >> > >> they want to integrate that new API and takes that burden off the >> >> > >> person making the change to utils. In theory we'd get to have our >> >> > >> cake and eat it too (i.e. frictionless iteration on an API endpoint >> >> > >> flagged @BETA, users have stable APIs they can rely on with >> >> > >> @STABLE), at the risk / cost of having a proliferation of >> >> > >> @DEPRECATED APIs littered behind us. >> >> > >> >> >> > >> My intuition is that the latter is actually significantly less work >> >> > >> for anyone that wants to modify utils vs. the former and the risk of >> >> > >> that long tail of deprecated API proliferation isn't that high. >> >> > >> >> >> > >>> I’m against creating any API boundaries we need to maintain for any >> >> > >>> external users >> >> > >> 100% agree. I think we get this as a free side-effect of a model >> >> > >> where we have STABLE flagged APIs and BETA, since it defers that >> >> > >> integration cost to *any* consumer's timeline. i.e. someone could >> >> > >> iterate on an API they need a change for in cassandra-analytics and >> >> > >> core cassandra can keep trucking with a now @DEPRECATED endpoint >> >> > >> until such time as it wants to integrate the new structure. >> >> > >> >> >> > >> One other point that's come up in conversation offline is around >> >> > >> bug-fixing; being able to fix bugs in implementation w/out consumers >> >> > >> having to also refactor to new API endpoints is just good hygiene >> >> > >> for limiting blast radius of changes. >> >> > >> >> >> > >> >> >> > >> On Tue, Aug 18, 2026, at 4:25 AM, Benedict Elliott Smith wrote: >> >> > >>> I’m hard -1 on this the >> >> > >>> >> >> > >>> I’m very pro code sharing between Cassandra projects, but these do >> >> > >>> not need any special handling - we just make sure the builds don’t >> >> > >>> break. I’m against creating any API boundaries we need to maintain >> >> > >>> for any external users >> >> > >>> >> >> > >>> On 2026/08/17 20:33:32 David Capwell wrote: >> >> > >>>>> They're all internal, this is a convenience to improve code >> >> > >>>>> sharing. >> >> > >>>> >> >> > >>>> Once they go into utils they are not “internal” (whatever that >> >> > >>>> means). Why I started this effort in the first place is that the >> >> > >>>> test utilities have been requested to be used in projects like >> >> > >>>> Cassandra-ecosystem, but also non-cassandra projects. Both users >> >> > >>>> need to know that a hot fix doesn’t break their build hence why I >> >> > >>>> propose basic properties you would expect: major versions might >> >> > >>>> have breaking changes, minor / patch won’t. For the classes >> >> > >>>> anyone has talked about moving here, non of them should have >> >> > >>>> issues with this; we are free to add new methods over time, but >> >> > >>>> removing causes issues for consumers. >> >> > >>>> >> >> > >>>>> to improve code sharing. >> >> > >>>> >> >> > >>>> Even if you think about this only for cassandra ecosystem, if I >> >> > >>>> depend on version 0.1.0 and we find a bug so get that fixed and >> >> > >>>> now we depend on 0.1.10… I shouldn’t expect to deal with breaking >> >> > >>>> changes. The mentality of “They’re all internal” as a >> >> > >>>> justification to not document these assumptions causes me concern >> >> > >>>> as breaking changes explicitly make it harder for parties to >> >> > >>>> depend on these classes; breaking changes make is so much harder >> >> > >>>> to “share code”. >> >> > >>>> >> >> > >>>>> We only care about versioning to ensure we don't break any builds >> >> > >>>> >> >> > >>>> What do you mean by this? Major versions I am ok with breaking >> >> > >>>> changes; minor / patch is what I want to avoid. We can add new >> >> > >>>> APIs without issue, the concern is only on removal. >> >> > >>>> >> >> > >>>>> and even decide when we upgrade the jar so can spot and fix any >> >> > >>>>> breakages. >> >> > >>>> >> >> > >>>> If we are upgrading to enable a new JDK change, I wouldn’t expect >> >> > >>>> users to have to rewrite all their tests, redo all their >> >> > >>>> collections, etc…. You shouldn’t have to worry about upgrading the >> >> > >>>> version cross minor / patch versions, as that should impose a no >> >> > >>>> breaking change rule. >> >> > >>>> >> >> > >>>> >> >> > >>>>> On Aug 14, 2026, at 3:06 PM, Benedict Elliott Smith >> >> > >>>>> <[email protected] <mailto:[email protected]>> wrote: >> >> > >>>>> >> >> > >>>>> Why are we defining this at all? They're all internal, this is a >> >> > >>>>> convenience to improve code sharing. We only care about >> >> > >>>>> versioning to ensure we don't break any builds, and we have all >> >> > >>>>> the builds, and even decide when we upgrade the jar so can spot >> >> > >>>>> and fix any breakages. >> >> > >>>>> >> >> > >>>>> Let's not overcomplicate things, or bind our future selves in red >> >> > >>>>> tape and regret. >> >> > >>>>> >> >> > >>>>> On 2026/08/14 17:57:40 Josh McKenzie wrote: >> >> > >>>>>> While I read your email I found myself wondering "To what are we >> >> > >>>>>> referring to when we say 'API'"? ;) >> >> > >>>>>> >> >> > >>>>>> Are you talking about a public interface? Or are you talking >> >> > >>>>>> about "any class that's public and any public method within a >> >> > >>>>>> public class"? >> >> > >>>>>> >> >> > >>>>>> If the latter, my primary theoretical concern is that if we pull >> >> > >>>>>> in code that has components that are scoped public for >> >> > >>>>>> cross-package accessibility within-project, promoting those to >> >> > >>>>>> "public by default" immediately calcifies their interface >> >> > >>>>>> whether we intend for that to be consumed or not. Basically, we >> >> > >>>>>> don't have an interim scope layer between "package private" and >> >> > >>>>>> "public" that corresponds to "project public". In theory the >> >> > >>>>>> post JDK9 modularity kind of provides that but then everyone >> >> > >>>>>> just add-opens bulldozes across things (the joys of legacy >> >> > >>>>>> code...). >> >> > >>>>>> >> >> > >>>>>> I think "Any interface that's public is a public API" is pretty >> >> > >>>>>> obvious to maintainers and users and good. I'm also good with >> >> > >>>>>> "anything public is an API unless otherwise documented" and we >> >> > >>>>>> add a simple annotation like @INTERNAL >> >> > >>>>>> <https://github.com/apiguardian-team/apiguardian/blob/main/src/main/java/org/apiguardian/api/API.java#L87> >> >> > >>>>>> from API Guardian to basically say "yeah, this is public, but >> >> > >>>>>> it's not intended for public consumption" (I think we should >> >> > >>>>>> roll our own to match our proposed lifecycles but that's a clear >> >> > >>>>>> example of the idea). >> >> > >>>>>> >> >> > >>>>>> I'm worried about the approach of "Any public method in a public >> >> > >>>>>> class is considered public API and you can't change it". I'd >> >> > >>>>>> prefer we start with a more constrained surface area we commit >> >> > >>>>>> to as being an API and widen it later if we find there's a need; >> >> > >>>>>> it's much harder to go in the other direction. >> >> > >>>>>> >> >> > >>>>>> On Fri, Aug 14, 2026, at 1:24 PM, David Capwell wrote: >> >> > >>>>>>> Josh and I talked about this offline and not perfectly in-sync >> >> > >>>>>>> so would be good to get other peoples views >> >> > >>>>>>> >> >> > >>>>>>> My take is that if you are adding the API to this shared repo >> >> > >>>>>>> we need to care about backwards compatibility so things should >> >> > >>>>>>> be PUBLIC by default (anything that is java public is part of >> >> > >>>>>>> the public interface and breaking changes are not allowed >> >> > >>>>>>> without a long enough deprecation window similar to >> >> > >>>>>>> Cassandra’s.). I think Josh is in favor of using a annotation >> >> > >>>>>>> to mark that a API is public, but without custom tooling I >> >> > >>>>>>> don’t think anyone will notice and then we will get to a >> >> > >>>>>>> effectively public state and breaking changes will be a >> >> > >>>>>>> nightmare to deal with for the community. So if you want to >> >> > >>>>>>> post the API here, it should be stable and we shouldn’t be >> >> > >>>>>>> putting APIs that have not been fleshed out first. >> >> > >>>>>>> >> >> > >>>>>>>> On Aug 7, 2026, at 8:16 AM, Josh McKenzie >> >> > >>>>>>>> <[email protected] <mailto:[email protected]>> wrote: >> >> > >>>>>>>> >> >> > >>>>>>>> One thing worth immediately calling out that we might want to >> >> > >>>>>>>> split out: we *could* do this work in Ant. >> >> > >>>>>>>> >> >> > >>>>>>>> It would be somewhat more imperative and brittle: we'd >> >> > >>>>>>>> explicitly orchestrate the build ordering in Ant, while >> >> > >>>>>>>> relying on the Gradle build inside Accord for its >> >> > >>>>>>>> cassandra-utils dependency resolution / source substitution. >> >> > >>>>>>>> That leaves us with a somewhat more complicated mixed >> >> > >>>>>>>> Ant/Gradle build relationship but it's entirely workable for >> >> > >>>>>>>> an interim time. >> >> > >>>>>>>> >> >> > >>>>>>>> So if the Gradle migration is a sticking point, we can break >> >> > >>>>>>>> that out into a separate discussion and CEP rather than making >> >> > >>>>>>>> it part of CEP-65. >> >> > >>>>>>>> >> >> > >>>>>>>> Doing so would mean retaining and extending some of the >> >> > >>>>>>>> complexity in our existing build system that a future >> >> > >>>>>>>> migration could remove, but it's not a crushing amount of >> >> > >>>>>>>> additional complexity. The benefit of doing that work here >> >> > >>>>>>>> with this CEP is that we have one more concrete build need >> >> > >>>>>>>> providing a reason to move toward a unified build stack, and >> >> > >>>>>>>> it fits the "clean things up and refactor as you're working on >> >> > >>>>>>>> things that could benefit from that work" approach many have >> >> > >>>>>>>> argued for in the past on the project. >> >> > >>>>>>>> >> >> > >>>>>>>> On Fri, Aug 7, 2026, at 10:58 AM, Josh McKenzie wrote: >> >> > >>>>>>>>> As per the previous ML thread: [DISCUSS] Forking Cassandra >> >> > >>>>>>>>> utilities into a separately released library >> >> > >>>>>>>>> <https://lists.apache.org/thread/7kllp45vvonsg7ggzxpz39c5kdcy7r6g>, >> >> > >>>>>>>>> David and I put together a draft of what we discussed and >> >> > >>>>>>>>> worked through some implications and requirements that came >> >> > >>>>>>>>> up as we tried to nail things down. >> >> > >>>>>>>>> >> >> > >>>>>>>>> The goal here is to provide a material backstop to continue >> >> > >>>>>>>>> our discussion and version it. As with all CEP DISCUSS >> >> > >>>>>>>>> threads, this is very fluid and none of it should be taken as >> >> > >>>>>>>>> settled or an implicit mandate. Let's see if we can make some >> >> > >>>>>>>>> progress on this long-standing pain point in our ecosystem. >> >> > >>>>>>>>> >> >> > >>>>>>>>> CEP-65 DRAFT: link >> >> > >>>>>>>>> <https://cwiki.apache.org/confluence/spaces/CASSANDRA/pages/446071230/CEP-65+cassandra-utils+-+A+shared+utility+library+for+the+cassandra+ecosystem+DRAFT> >> >> > >>>>>>>>> >> >> > >>>>>>>>> *Why You Should Read This Draft:* >> >> > >>>>>>>>> 1. Build system impact: we need a parent project and one of >> >> > >>>>>>>>> its submodule to depend on another submodule. We're proposing >> >> > >>>>>>>>> freezing ant's API surface area, maintaining that into >> >> > >>>>>>>>> perpetuity, and moving to gradle going forward. >> >> > >>>>>>>>> 2. Branching model: read the draft to see what "One Branch to >> >> > >>>>>>>>> Rule Them All" means. >> >> > >>>>>>>>> 3. API Lifecycle: Is @BETA/@STABLE/@DEPRECATED enough? Do we >> >> > >>>>>>>>> need a @PRIVATE? >> >> > >>>>>>>>> 4. To Release or Not To Release: we're proposing consumers >> >> > >>>>>>>>> embed this as a submodule initially to minimize friction in >> >> > >>>>>>>>> moving shared code into a shared space. >> >> > >>>>>>>>> We have 1 outstanding unanswered question we didn't come up >> >> > >>>>>>>>> with an opinionated proposal for: >> >> > >>>>>>>>> >> >> > >>>>>>>>> What should unannotated methods and classes in the library be >> >> > >>>>>>>>> considered by potential consumers? @PRIVATE? @PUBLIC? Should >> >> > >>>>>>>>> we lint and fail on any class without a top-level annotation >> >> > >>>>>>>>> forcing us to make a choice on our dev list [DISCUSS] threads >> >> > >>>>>>>>> whenever we bring in new things? >> >> > >>>>>>>>> >> >> > >>>>>>>>> There's no timeline on this thread; let's keep turning the >> >> > >>>>>>>>> crank on this until we've hit our pareto-polish frontier. ;) >> >> > >>>>>>>>> >> >> > >>>>>>>>> ~Josh >> >> > >>>>>>>>> >> >> > >>>>>>>>> >> >> > >>>>>>>> >> >> > >>>>>> >> >> > >>>> >> >> > >>>> >> >> > >>> >> >> > >> >> >> > >> >
