Release process

​

Commits

<type>(<scope>)!?: <short summary>

<brief explanation when needed>

​

Repository and tag authority

​

Changelog and versions

• MAJOR: incompatible stable-interface changes after 1.0
• MINOR: features and potentially breaking pre-1.0 changes
• PATCH: fixes and internal changes

​

Stable-v1 database compatibility

​

Major-version schema epochs

1. The final release of the outgoing major is the bridge. It accepts the last canonical schema, applies one reviewed conversion, and writes an application-owned marker such as schema_state(epoch, version).
2. The new major starts from one declarative baseline. Fresh installs create it directly; the normal runtime drops older migrations, fingerprints, and release-specific checksums. Git tags retain that history.
3. Migrations within the new major use the application-owned epoch/version marker rather than PRAGMA user_version. Some explicit compatibility marker remains mandatory so partial or hand-edited databases fail closed.
4. Older databases upgrade through the bridge release. If direct legacy conversion becomes necessary, it belongs in a separate offline upgrade command, not normal server startup.
5. Repeat only at the next major boundary: v1 carries v1 migrations, v2 starts a new epoch, and so on.

​

Already-adopted pre-identity archives

1. Preserve a live browser session before the window if an existing OIDC account must be bound; verified-email fallback is intentionally absent.
2. Stop Suchi and every CLI/import writer. Require the exact pre-identity fingerprint, valid lineage/version, clean integrity and foreign keys, and the reviewed 0005 checksum before changing the database.
3. Copy the complete quiescent data directory and effective configuration to verified storage outside DATA_DIR; keep the old binary/config. A normal live database copy is not rollback.
4. Apply the exact 0005 SQL through the table-rebuild transaction, restore user_version = 1 and stable-v1, then require the exact stable schema-1 fingerprint, integrity, foreign keys, stable user IDs, and expected counts before starting any writer.
5. Start the current binary. It admits that exact schema-1 state, applies active migrations 0002–0005, and requires the schema-5 manifest. From the preserved session, use Sync from identity provider and verify the same user ID gains issuer/subject, a retained user.oidc_bound row, a replacement cookie, and unchanged ownership.

​

Release checklist

1. Build and verify the web app from the release sources:
   make ui-check
   make ui-verify
   
   core/ui/spa/dist remains ignored. CI builds it once from the immutable release revision, passes that artifact to every tagged binary build, and rebuilds it in the pinned Bun stage for container images.
2. Move the [Unreleased] entries under the new version and date. Update developmentVersion in distro/cmd/suchi/main.go to the current source version line with a -dev suffix.
3. Review every OCR, content and LLM pipeline revision changed since the previous release. distro/cmd/suchi/pipeline_proposals.go is the tagged automatic reminder policy:
   • Keep 0 when that pipeline has no recommended automatic upgrade.
   • Set a field to the current pipeline revision when existing successful results should receive a Processing update reminder.
   • Leave an earlier positive recommendation unchanged when a newer processing change is not worth prompting. This preserves the earlier recommendation for archives that skipped releases without opting in the newer revision.
   Each field is independent and cannot exceed its compiled pipeline revision. Commit this file with the release metadata; never inject or override the policy in the build workflow.
4. Confirm the shipped Microsoft OAuth registration still permits personal and work/school device-code sign-in.
5. Run the local verification suite:
   make check
   make security-check
   make smoke
   make bench-check
   docker build --check .
   docker compose config --quiet
   make docs-check
   git diff --check
   
6. Manually exercise behavior that depends on external services or accounts, including Microsoft sign-in, configured email providers, and hosted LLMs affected by the release.
7. Recheck public size, memory, startup, network, and feature claims against the accepted benchmark and the final build.
8. Commit the release metadata on main, create a signed annotated tag, and push the exact commit and tag to GitHub:
   export VERSION=v0.4.1
   git tag -s "$VERSION" -m "suchi ${VERSION#v}"
   ./hack/verify-release-tag.sh "$VERSION"
   git push gh main
   git push gh "refs/tags/$VERSION"
   
9. Dispatch the manual release workflow:
   make release VERSION="$VERSION"
   
   This verifies that the local and GitHub tags resolve to the same commit. Use PUBLISH=false to validate the signed tag and release gates without packaging or publishing release artifacts. The checked-in proposal policy remains identical across every published binary and image. Zero thresholds do not cancel existing reminders, and explicit rescans remain available.

​

Publishing container images without Actions

export VERSION=v0.4.1
export IMAGE=ghcr.io/johnnybravo-xyz/suchi
export CACHE_AMD64="$IMAGE:buildcache-amd64"
export CACHE_ARM64="$IMAGE:buildcache-arm64"

git worktree add --detach "/tmp/suchi-$VERSION" "$VERSION"
cd "/tmp/suchi-$VERSION"

printf '%s' "$CR_PAT" |
  docker login ghcr.io -u "$GITHUB_USER" --password-stdin
unset CR_PAT

​

Build on native architecture hosts

docker buildx build \
  --file Dockerfile \
  --target standard \
  --platform linux/amd64 \
  --build-arg VERSION="$VERSION" \
  --build-arg REVISION="$(git rev-parse HEAD)" \
  --tag "$IMAGE:$VERSION-amd64" \
  --label org.opencontainers.image.source=https://github.com/johnnybravo-xyz/suchi \
  --label org.opencontainers.image.version="$VERSION" \
  --label org.opencontainers.image.licenses=AGPL-3.0 \
  --cache-from type=registry,ref="$CACHE_AMD64" \
  --cache-to type=registry,ref="$CACHE_AMD64",mode=max \
  --provenance=mode=max \
  --sbom=true \
  --push .

docker buildx build \
  --file Dockerfile \
  --target standard \
  --platform linux/arm64 \
  --build-arg VERSION="$VERSION" \
  --build-arg REVISION="$(git rev-parse HEAD)" \
  --tag "$IMAGE:$VERSION-arm64" \
  --label org.opencontainers.image.source=https://github.com/johnnybravo-xyz/suchi \
  --label org.opencontainers.image.version="$VERSION" \
  --label org.opencontainers.image.licenses=AGPL-3.0 \
  --cache-from type=registry,ref="$CACHE_ARM64" \
  --cache-to type=registry,ref="$CACHE_ARM64",mode=max \
  --provenance=mode=max \
  --sbom=true \
  --push .

docker buildx imagetools create \
  --tag "$IMAGE:$VERSION" \
  "$IMAGE:$VERSION-amd64" \
  "$IMAGE:$VERSION-arm64"

docker buildx imagetools inspect "$IMAGE:$VERSION"
docker pull --platform linux/amd64 "$IMAGE:$VERSION"
docker pull --platform linux/arm64 "$IMAGE:$VERSION"

docker buildx imagetools create \
  --tag "$IMAGE:latest" \
  "$IMAGE:$VERSION"
docker buildx imagetools create \
  --tag "$IMAGE:latest-full" \
  "$IMAGE:$VERSION-full"

​

Automation

• checks.yml runs the complete repository validation graph on pushes to main, pull requests and manual dispatch.
• ci.yml runs formatting, tests, vet, lint, documentation release-metadata checks, UI checks and browser tests when called by it.
• smoke.yml tests the built images and ingest paths when called by it. Both variants are rebuilt with the exported AnyDoc context and an unusable Rust base to catch accidental recompilation; binary and license bytes must match the export before the usual ingestion checks run.
• restore-drill.yml validates backup restoration when called by it.
• release.yml publishes only when manually dispatched from an existing signed annotated tag. Its preflight repeats the complete reusable validation graph, race tests, security scans, local smoke and benchmark gates, Docker checks and documentation validation. Only jobs that publish releases, packages or keyless signatures receive the corresponding write permissions.