From e267f4f84ad84707aec0202a7a2c066b94f4292b Mon Sep 17 00:00:00 2001 From: James Maes Date: Fri, 6 Nov 2026 08:45:34 -0600 Subject: [PATCH] docs(release): prepare the 0.1.0 release on the 0.1 train Add CHANGELOG.md for the first published release and docs/RELEASES.md describing the shared ci-workflows versioning (develop SNAPSHOT, release/0.1 RC.N, tag vX.Y.Z stable), registry consumption and the maintainer path. README now states the 0.1 train (0.1.0-RC.1 published, 0.1.0 cut by tag) instead of the coordinated snapshot; SNAPSHOT-RELEASE.md is marked historical. The POM revision stays 0.1.0-SNAPSHOT on develop because the workflow owns version computation. Verified locally: ./mvnw.cmd verify, 33 tests, 0 failures/errors/skips, JaCoCo gates met. Co-Authored-By: Claude Fable 5.1 Signed-off-by: James Maes --- CHANGELOG.md | 33 +++++++++++++++++++ README.md | 15 +++++---- docs/RELEASES.md | 69 ++++++++++++++++++++++++++++++++++++++++ docs/SNAPSHOT-RELEASE.md | 2 ++ 4 files changed, 113 insertions(+), 6 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/RELEASES.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..18b0859 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Changelog + +## 0.1.0 + +First published release of `com.kingsrook.qbits:qbit-redis`, built on the +published QQQ `4.1.0-RC.21` core and Jedis `7.2.0` (Java 21). The release +candidate `0.1.0-RC.1` was published from `release/0.1` (source `6b0814d`, the +`develop` head `0bafd25` plus the CI version bump); the stable `0.1.0` is cut by +tagging `v0.1.0` on that train. See [docs/RELEASES.md](docs/RELEASES.md). + +- Named, bounded Redis connections with required TLS (hostname verification on), + host-provided credentials and TLS providers resolved at runtime, startup + validation/ping of every pool, failed-startup cleanup and QInstance isolation. +- Shared value cache (`RedisAccess.cache`): collision-safe namespaces, explicit + size limits, positive TTL on every write, atomic SET with expiry and atomic + GETEX read-and-renew; outages throw rather than reading as misses. +- Trusted domain Lua through `RedisAccess.scripts` with EVALSHA/NOSCRIPT recovery. +- Redis Pub/Sub realtime transport (candidate) with bounded hint queue, resync + on overflow/reconnect, per-node heartbeat and transport metrics. +- Framework health check `redis.connections` with aggregate pool metrics; an + opt-in per-connection write probe (`withWriteHealthKeyPrefix`, default off, + `SET NX PX 1000` under a reserved prefix) reports `writeChecks`. +- Admin app and widgets with native help bundle; no host SQL schema. +- Qualification fixtures (not runtime behavior): controlled replica promotion, + stable endpoint switch, primary fencing and partition healing on real Redis + containers ([docs/TOPOLOGY-QUALIFICATION.md](docs/TOPOLOGY-QUALIFICATION.md)). + +Compared with the isolated development build `0.1.0-forge.54adcfed62b0` that +GG Forge qualified, the published artifact compiles against the same QQQ +`4.1.0-RC.21` (now the POM default rather than a command-line override), adds +the optional write-health prefix and `writeChecks` detail, rewords the health +check status messages, and adds test fixtures and CI. No API was removed and +no default behavior changed. diff --git a/README.md b/README.md index 61c1f00..220ebe8 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ # QBit Redis Reusable Redis connections and bounded shared caches for QQQ applications. -**Coordinated feature snapshot published; not a stable/GA release.** Track -[QQQ #1295](https://github.com/QRun-IO/qqq/issues/1295) and [completed milestone and follow-ups](docs/TODO.md). -See [published snapshot](docs/SNAPSHOT-RELEASE.md) for current normal-flow evidence, -exact compatible versions and the explicitly deferred optional scenarios. +Release train `0.1`: candidate `0.1.0-RC.1` is published to the Gitea Maven +registry (`com.kingsrook.qbits:qbit-redis`, QQQ `4.1.0-RC.21`, Java 21); the +stable `0.1.0` is cut from the same train. See [CHANGELOG.md](CHANGELOG.md) and +[release operations](docs/RELEASES.md) for consumption, versioning and the +maintainer path, and [follow-ups](docs/TODO.md) for the optional scenarios that +no release declares supported. [SNAPSHOT-RELEASE.md](docs/SNAPSHOT-RELEASE.md) +is the historical coordinated-snapshot record. ## Host integration @@ -96,7 +99,7 @@ or proof that every application command/key is authorized. A writable stale primary can pass; topology fencing must remain an infrastructure guarantee. The host decides whether this check gates readiness. Do not enable the probe on an existing ACL until its dedicated prefix and write permission are configured. -This option is currently an unpublished candidate. +This option is off by default and first ships in 0.1.0. Other qbits consume only `com.kingsrook.qbits.redis.api`: `RedisAccess`, `RedisNamespace`, `RedisCache`, `RedisScript`, `RedisScriptExecutor`, @@ -168,7 +171,7 @@ Java 21, Maven wrapper and Docker are required for the full current tests: .\mvnw.cmd test ``` -The current candidate uses the published QQQ `4.1.0-RC.21` and Jedis `7.2.0`. Tests use +The 0.1 release train uses the published QQQ `4.1.0-RC.21` and Jedis `7.2.0`. Tests use real disposable Redis containers. They cover sharing, expiry, isolation, outages, registration, failed startup cleanup, credential-error redaction, lifecycle, authentication, bounded pool exhaustion and TLS. TLS tests generate temporary diff --git a/docs/RELEASES.md b/docs/RELEASES.md new file mode 100644 index 0000000..243ce95 --- /dev/null +++ b/docs/RELEASES.md @@ -0,0 +1,69 @@ +# Release operations + +The current release train is `0.1`. Its candidate `0.1.0-RC.1` is published to +the Gitea Maven registry from `release/0.1` (tag `v0.1.0-RC.1`, source +`6b0814d83e18f70e3ea315a99e5aece1a562a213`). The stable `0.1.0` is cut by +tagging `v0.1.0` on that train as described below. Changes are listed in +[CHANGELOG.md](../CHANGELOG.md). Gitea (`git.kof22.com/QRun-IO/qbit-redis`) is +primary for source, pull requests, CI, packages and releases; GitHub is a +shadow/archive and its workflows are historical. + +## Use the Maven registry + +Configure the consuming application's Maven repository setup with repository ID +`qrun-io` and URL `https://git.kof22.com/api/packages/QRun-IO/maven` (releases +enabled). The registry requires authentication for reads as well as writes: +match the ID to a `` entry in your private `settings.xml` that references +your managed username/token through environment variables or encrypted Maven +credentials. Never commit a token or put it on a command line. Then depend on +`com.kingsrook.qbits:qbit-redis:`; QQQ `4.1.0-RC.21` and Jedis resolve +from Maven Central. Verify the downloaded JAR/POM against the hashes recorded +for the release before adopting it. + +## Versioning + +The POM version is the `revision` property. On `develop` it stays +`0.1.0-SNAPSHOT` and is never hand-set: the shared +`KofTwentyTwo/ci-workflows` Maven workflow (called by +`.gitea/workflows/build.yaml` on every push) computes and commits versions. + +| Ref | Build | Published version | +| --- | --- | --- | +| feature branches, pull requests, `main` | `mvn verify` only | none | +| `develop` | `mvn deploy` | current `X.Y.0-SNAPSHOT` (bumped to the next minor after a release merges back) | +| `release/X.Y` | `mvn deploy`, bump commit, tag `vX.Y.0-RC.N` | `X.Y.0-RC.N` | +| tag `vX.Y.Z` | `mvn deploy`, bump commit pushed to `main` | `X.Y.Z` | +| `hotfix/*` | `mvn deploy`, bump commit, tag | `X.Y.(Z+1)` | + +The workflow runs the tests once inside `mvn deploy` on the `container-build` +runner, which provides the Docker daemon the Redis Testcontainers suites need. + +## Maintainer release path + +1. Merge reviewed changes into `develop` through a normal pull request; the + `develop` run publishes the SNAPSHOT. +2. Merge `develop` into `release/0.1` (pull request or fast-forward). The push + publishes the next `0.1.0-RC.N`, commits `Bump version to 0.1.0-RC.N [skip ci]` + and tags `v0.1.0-RC.N` on that bump commit. Consumers qualify the RC. +3. Bring `main` to the release-train head before tagging: the tag run pushes its + `Bump version to 0.1.0` commit with `git push origin HEAD:main`, which must be + a fast-forward. `main` currently carries CI-only commits with different SHAs + from the equivalent `develop` commits, so it must be reset or merged to the + `release/0.1` head first. +4. Tag the qualified source: `git tag -s v0.1.0 ` and push the + tag to origin only. The tag run sets `revision` to `0.1.0`, deploys + `com.kingsrook.qbits:qbit-redis:0.1.0` to the registry and pushes the bump + commit to `main`. A passing run alone does not prove publication: resolve the + exact version's JAR/POM from the registry with an authenticated client and + record their SHA-256 values here. +5. Create a Gitea release for `v0.1.0` (the shared workflow does not), attach the + same `qbit-redis-0.1.0.jar`, `qbit-redis-0.1.0.pom` and a flat `SHA256SUMS`, + read them back with the approved forge identity, then publish. Never replace + different bytes under a released version. +6. Merge `release/0.1` back into `develop`; the next `develop` run moves it to + `0.2.0-SNAPSHOT`. + +Publication is separate from host adoption. The optional scenarios in +[TODO.md](TODO.md) (QQQ #1300/#1301/#1302) are not declared supported by a +release; [TOPOLOGY-QUALIFICATION.md](TOPOLOGY-QUALIFICATION.md) records what the +fixtures demonstrate. diff --git a/docs/SNAPSHOT-RELEASE.md b/docs/SNAPSHOT-RELEASE.md index 677e351..1e03af9 100644 --- a/docs/SNAPSHOT-RELEASE.md +++ b/docs/SNAPSHOT-RELEASE.md @@ -1,5 +1,7 @@ # Coordinated candidate snapshot +Historical record. The 0.1 release train (`0.1.0-RC.1` published from `release/0.1`, stable `0.1.0` cut by tag) supersedes the CircleCI snapshot path below; see [RELEASES.md](RELEASES.md). + Status, 2026-10-22: source is uploaded, canonical branch CI is verified and enforced, and the required Core snapshot is published. Publication of Redis `0.1.0-SNAPSHOT` through the canonical `develop` pipeline remains to be verified. This is not a production deployment checklist or an RC certification. ## Local evidence -- 2.54.0