qbit-redis/docs/RELEASES.md

# 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 `<server>` 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:<version>`; 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 <release/0.1 head>` 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.