generated from coulomb/repo-seed
116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
# Release Runbook 0.1.0
|
|
|
|
Date: 2026-05-14
|
|
Release posture: controlled preview
|
|
|
|
## Purpose
|
|
|
|
This runbook defines the repeatable checks and operator expectations for the
|
|
`kontextual-engine` `0.1.0` controlled preview. It is a release envelope, not a
|
|
new product scope.
|
|
|
|
## Preflight
|
|
|
|
Run from `/home/worsch/kontextual-engine`:
|
|
|
|
```sh
|
|
.venv/bin/python -m pytest -q
|
|
python3 -m build --sdist --wheel --outdir /tmp/kontextual-release-smoke-20260514T010625Z/dist
|
|
```
|
|
|
|
Expected evidence for this pass:
|
|
|
|
- full suite: `166 passed`, `15 skipped`,
|
|
- package build: `kontextual_engine-0.1.0.tar.gz` and
|
|
`kontextual_engine-0.1.0-py3-none-any.whl`,
|
|
- clean install smoke: wheel plus `[service]` extra imports
|
|
`kontextual_engine`, creates `create_app(ServiceRuntime())`, and attaches
|
|
`app.state.kontextual_runtime`.
|
|
|
|
## CMIS Evidence
|
|
|
|
Run the selected OpenCMIS Browser Binding baseline through `guide-board` and
|
|
`open-cmis-tck`. On this workstation, use port `8010` for the temporary engine
|
|
endpoint because port `8000` is already occupied by another local service.
|
|
|
|
Current accepted evidence:
|
|
|
|
- run: `run-20260514T003705Z`,
|
|
- assessment: `cmis-browser-baseline`,
|
|
- result: completed,
|
|
- policy: `0` unexpected findings and `0` waivers,
|
|
- object/content: pass,
|
|
- only warning: local HTTP loopback transport.
|
|
|
|
The local HTTP warning is accepted only for harness runs. Preview deployments
|
|
must serve production-facing CMIS access points behind HTTPS termination.
|
|
|
|
## Runtime Start
|
|
|
|
The app is currently exposed as a FastAPI factory:
|
|
|
|
```sh
|
|
PYTHONPATH=src .venv/bin/uvicorn 'kontextual_engine.api.app:create_app' \
|
|
--factory \
|
|
--host 127.0.0.1 \
|
|
--port 8010
|
|
```
|
|
|
|
For deployment, instantiate `ServiceRuntime` with explicit durable repository,
|
|
blob storage, and policy gateway adapters instead of relying on the default
|
|
in-memory runtime.
|
|
|
|
## Health And Observability
|
|
|
|
Required operator checks:
|
|
|
|
- `/health` returns process health.
|
|
- `/ready` returns readiness for the configured runtime.
|
|
- `/version` returns the service version.
|
|
- `/openapi.json` is available when the service extra is installed.
|
|
- Pytest performance history is retained under
|
|
`.pytest_cache/kontextual/performance-history.json` during development runs.
|
|
|
|
Performance drift warnings are advisory unless reproduced under a quiet system
|
|
baseline. Keep the compact history file for trend awareness; use dedicated
|
|
profiling experiments for detailed performance investigations.
|
|
|
|
## Data Safety
|
|
|
|
Preview deployments must define:
|
|
|
|
- registry persistence location and backup schedule,
|
|
- blob backend and backup or bucket-versioning strategy,
|
|
- restore rehearsal for registry plus blob content,
|
|
- retention policy for raw assessment artifacts and logs,
|
|
- rollback point before migrations or adapter changes.
|
|
|
|
For SQLite-backed previews, stop writes before copying the database or use a
|
|
SQLite backup method. For local blob storage, back up the whole content-addressed
|
|
root. For S3, enable bucket versioning or equivalent object protection and back
|
|
up IAM/policy configuration alongside data.
|
|
|
|
## Rollback
|
|
|
|
Rollback for `0.1.0` preview means:
|
|
|
|
1. Stop the service or remove it from routing.
|
|
2. Preserve current logs, State Hub references, registry database, and blob
|
|
root/bucket state for analysis.
|
|
3. Restore the previous package artifact and previous registry/blob snapshot.
|
|
4. Re-run `/health`, `/ready`, smoke import, and a small read/write scenario.
|
|
5. Record the rollback reason in State Hub before resuming external traffic.
|
|
|
|
## Tag Gate
|
|
|
|
Do not create the release tag until:
|
|
|
|
- full venv tests pass,
|
|
- OpenCMIS selected baseline is persisted,
|
|
- package build and clean install smoke pass,
|
|
- security/config/storage review is current,
|
|
- State Hub consistency is clean,
|
|
- release notes are updated.
|
|
|
|
No tag is created by this runbook automatically.
|