upgrade-versions

name	upgrade-versions
description	Bump pinned versions of (A) Java fdb-record-layer / fdb-relational artifacts or (B) the FDB C++ wire protocol. Captures every spot the version is pinned, the codegen steps, and the conformance gotchas. Pass `java` or `fdb-cpp` to pick which procedure to run.
user-invocable	true

Upgrade procedure

This project pins two independent versions:

• A — Java fdb-record-layer / fdb-relational artifacts. Currently 4.11.1.0. Used by the conformance Java server and as the canonical source for proto schemas.
• B — FDB C++ wire protocol. Currently 7.3.77. Used by the pure-Go FDB client (pkg/fdbgo/) — wire frames, request/reply types, error codes, atomic mutation semantics all match this version.

These versions are independent — bumping Java does not require bumping FDB C++ or vice versa. Each procedure has its own canonical command sequence and its own set of "things you must touch."

Input

• /upgrade-versions java → run procedure A.
• /upgrade-versions fdb-cpp → run procedure B.
• /upgrade-versions (no arg) → ask the user which one.

If the user passes a target version (e.g. /upgrade-versions java 4.12.0.0), use it. Otherwise:

• For java: pick the latest 4.x.y.0 listed at https://repo1.maven.org/maven2/org/foundationdb/fdb-record-layer-core/. Verify the same version exists for fdb-relational-api and fdb-relational-core — if not, pick the highest version that exists in all three.
• For fdb-cpp: pick the latest 7.3.x tag at https://github.com/apple/foundationdb/tags. Do not jump major (7.x → 8.x) without explicit user confirmation; major bumps move serialization formats and error codes.

Always confirm the picked version with the user before editing any files. Bumping is destructive — wrong version means the rest of the procedure either fails midway or lands a broken pin.

---

Procedure A — Java fdb-record-layer / fdb-relational

What you're touching

Surface	Why
MODULE.bazel — maven.install.artifacts	The version of every fdb-record-layer / fdb-relational jar resolved by Bazel
fdb-record-layer/ (gitignored submodule)	Local git checkout for source reading + proto syncing
proto/apple/*.proto	Apple's proto files copied from the submodule. Compiled into both Go (gen/*.pb.go) and Java (libapple_proto-speed.jar). When Java's compiled proto classes drift from the maven jar's proto classes the conformance server hits NoSuchFieldError at static-init time.
gen/*.pb.go (auto)	Regenerated by just generate from proto/apple/*.proto. Always commit the regenerated output.
CLAUDE.md "Java source reference" prose	One-line version mention; keep it accurate.
TODO.md header line	One-line version mention; keep it accurate.

Steps

1. Confirm Maven artifact availability for the target version. fdb-relational-* started publishing later than fdb-record-layer-core, so a version that works for one may not exist for the others.

   for art in fdb-record-layer-core fdb-relational-api fdb-relational-core; do
     curl -sf "https://repo1.maven.org/maven2/org/foundationdb/$art/$VERSION/$art-$VERSION.pom" >/dev/null \
       && echo "OK $art $VERSION" || echo "MISSING $art $VERSION"
   done
   

   If any artifact is missing, pick a higher version where all three exist.

2. Update the local submodule checkout. It's gitignored — it lives at fdb-record-layer/ in the repo root.

   cd fdb-record-layer
   git fetch origin --tags
   git checkout $VERSION
   cd ..
   

   Sanity-check: git -C fdb-record-layer log --oneline -1 should show the release commit for $VERSION.

3. Bump MODULE.bazel. Update all three artifacts in the maven.install block to the same version:

   "org.foundationdb:fdb-record-layer-core:$VERSION",
   "org.foundationdb:fdb-relational-api:$VERSION",
   "org.foundationdb:fdb-relational-core:$VERSION",
   

4. Run bazel mod tidy to refresh the resolved Maven dep set:

   bazelisk mod tidy
   

5. Sync the proto files. This is the step the conformance test breaks if you skip.

   diff -q proto/apple/ fdb-record-layer/fdb-record-layer-core/src/main/proto/
   

   For every file that differs, copy the new version from the submodule into proto/apple/. Skip BUILD.bazel (it lives only on our side).

   for f in $(diff -q proto/apple/ fdb-record-layer/fdb-record-layer-core/src/main/proto/ \
     | awk '/and.*differ/ {print $2}' | xargs -n1 basename); do
     cp "fdb-record-layer/fdb-record-layer-core/src/main/proto/$f" "proto/apple/$f"
   done
   

   Read the diff before committing: pure additive changes (new fields / messages / enum values) are safe; renames or removals require code-side adjustments.

6. Regenerate Go proto code.

   just generate
   

   Then run just gazelle to update BUILD files if any new files appeared.

7. Update prose references. Two files mention the version explicitly:

   • CLAUDE.md — the "Java source reference" section. Update the tag and Maven artifact mention.
   • TODO.md — the header line "Java Record Layer version: X.Y.Z.W".

8. Build + test.

   just build
   just test
   

   The conformance test (//conformance:conformance_test) is the canary — if proto sync is wrong, it fails with NoSuchFieldError: ... PXxx_descriptor from a static initializer in fdb-relational-core, then cascades into HTTP timeouts as the Java server is left in a half-initialized state. Resolve by re-syncing the offending proto file from the submodule.

9. Commit. All proto changes + regenerated gen/*.pb.go + MODULE.bazel + prose files in one commit. Short title (upgrade Java record-layer to $VERSION) plus a body that records WHY the bump (matching ecosystem release, unblocking specific work).

Common failures

• NoSuchFieldError: ... PXxx_descriptor in conformance test. Our locally-compiled proto/apple/libapple_proto-speed.jar is on the conformance test's classpath BEFORE the Maven jar. When proto/apple/*.proto is older than the Maven jar's compiled-in protos, fdb-relational-core's static init references a descriptor field our jar lacks. Fix: sync the proto file (step 5).
• Maven resolution picks an older fdb-record-layer-core via transitive deps. Rare; if it happens, pin the exact version in MODULE.bazel and run bazel mod tidy.
• Submodule on an older tag than the bumped version. git -C fdb-record-layer log --oneline -1 should match. Step 2 handles this; if you skipped it the proto diff in step 5 is misleading.

---

Procedure B — FDB C++ wire protocol

What you're touching

Surface	Why
MODULE.bazel — bazel_dep(name = "foundationdb", ...)	The pinned C++ source archive Bazel fetches
MODULE.bazel — module(name = "foundationdb", version = ...) (inside archive_override.patch_cmds)	The version embedded in the patched MODULE.bazel for the foundationdb module
MODULE.bazel — archive_override.strip_prefix + urls	Both reference the version literally
.bazelrc — test --test_env=FDB_VERSION=...	Version env var visible to test setups (testcontainers, etc.)
pkg/fdbgo/wire/types/*_generated.go (auto)	Regenerated by just generate-wire-types from the new C++ source via the schema extractor
pkg/fdbgo/wire/serializer.go doc comment	"Source: flow/include/flow/flat_buffers.h (FDB X.Y.Z)" — update the version string
pkg/fdbgo/README.md	Mentions the FDB version twice; keep it accurate
pkg/fdbgo/client/CRASH_BUG.md	Mentions Docker image tags foundationdb/foundationdb:X.Y.Z; keep accurate
CLAUDE.md "Baseline numbers" + similar prose	Mentions FDB version in benchmark context

Steps

1. Confirm tag availability.

   curl -sf "https://github.com/apple/foundationdb/archive/refs/tags/$VERSION.tar.gz" -o /dev/null -I | head -1
   

   Expect 200 OK. Also check the Docker image:

   docker manifest inspect foundationdb/foundationdb:$VERSION >/dev/null && echo OK || echo MISSING
   

2. Confirm wire-protocol compatibility. A patch bump within a minor line (e.g. 7.3.x → 7.3.y) is wire-compatible. A 7.3 → 7.4 minor bump may add new request/reply types but should remain backwards-compatible for the existing wire frames. A 7.x → 8.x major bump moves serialization in non-trivial ways — get explicit user confirmation before proceeding. Read FoundationDB release notes for the new version.

3. Bump MODULE.bazel. Replace the version in four places inside the foundationdb block:

   bazel_dep(name = "foundationdb", version = "$VERSION")
   ...
   module(name = "foundationdb", version = "$VERSION")
   ...
   strip_prefix = "foundationdb-$VERSION",
   urls = ["https://github.com/apple/foundationdb/archive/refs/tags/$VERSION.tar.gz"],
   

4. Bump .bazelrc.

   test --test_env=FDB_VERSION=$VERSION
   

5. Regenerate wire types. This invokes the C++ schema extractor against the new source archive Bazel fetched.

   just generate-wire-types
   just gazelle
   

   Inspect the diff in pkg/fdbgo/wire/types/*_generated.go. Pure additive changes (new fields / new types) are safe and the generator output is deterministic. Field-removal or type-rename diffs require call-site fixes elsewhere in pkg/fdbgo/.

6. Update prose / version-string references. Each of these files mentions the FDB version literally; sweep with grep:

   grep -l "$OLD_VERSION" pkg/fdbgo/wire/serializer.go pkg/fdbgo/README.md pkg/fdbgo/client/CRASH_BUG.md CLAUDE.md
   

   Replace with $VERSION.

7. Build + test.

   just build
   just test
   

   The pure-Go client tests (//pkg/fdbgo/client:client_test) run against an FDB Docker container at $VERSION. If the wire format changed in a way the regenerated types don't capture, those tests fail with parse errors or unexpected error codes. Investigate by:

   • reading the FDB release notes for the version delta;
   • re-running the schema extractor manually to capture stderr (bazelisk run //cmd/fdb-schema-extract);
   • comparing one or two regenerated *_generated.go files by hand against the previous version.

8. Run the binding stress for one seed as a smoke test:

   just binding-stress 1 100
   

   The binding tester's Python reference client compares against our Go stack — wire-format drift surfaces here even if the regular tests pass.

9. Commit. Bundle MODULE.bazel + .bazelrc + regenerated *_generated.go + prose files. Short title (upgrade FDB C++ to $VERSION) plus a body that calls out: any new wire types added, any behavior changes in the release notes that affect us, binding-stress smoke result.

Common failures

• pkg/fdbgo/wire/types/*_generated.go includes a _generated.go file we didn't author. Schema extractor produced a new wire type. If it's something we use, integrate it; if not, register it in cmd/fdb-schema-extract/extract.h and main.cpp per the policy in CLAUDE.md.
• Client tests fail with unknown error code 21XX. New error code in the FDB version. Map it in pkg/fdbgo/client/errors.go (retryable / non-retryable / resource-constrained / etc.) per the same classification C++ uses (consult fdbclient/include/fdbclient/FDBOptions.h).
• Binding stress fails on seeds that previously passed. Real wire-protocol regression. Check FDB's release notes for serialization changes; if our regenerated wire types are correct but behavior diverges, the divergence is in our hand-written serializer adapter (pkg/fdbgo/wire/serializer.go) and needs a code fix.

---

Both procedures — closing checklist

• All version references updated consistently (run grep -rn "$OLD_VERSION" . and verify any remaining hits are intentional, e.g. historical context in handovers / RFCs).
• just test is green.
• git status shows only files mentioned in the procedure above (catch accidental edits).
• Commit message records WHY (matching ecosystem release / unblocking specific feature work / security fix in upstream).
• Push to the current shift branch — version bumps go through PR review like any other change. Never push directly to master.