Skip to content

first_release_readiness_plan.md

Latest commit

 

History

History
314 lines (271 loc) · 12.1 KB

first_release_readiness_plan.md

File metadata and controls

314 lines (271 loc) · 12.1 KB
Raw

First Release Readiness Plan

This plan tracks what must be true before the first public release of ai-memory-hub. It complements release_container_docs_plan.md, which focuses on container and docs publishing mechanics. This plan covers the broader release surface: repository governance, PR policy, security posture, release artifacts, Docker publishing, documentation, and launch readiness.

See release_ci_gap_analysis.md for the split between automated release checks and the remaining repository-setting or external-client work. See release_security_scan_notes.md for the first-release security scan results and remaining hardening backlog.

Release Goal

Ship v0.1.0 as a credible first public release:

  • users can understand what the project does within one minute;
  • a clean checkout can run the documented quick start;
  • CI is green and visible;
  • releases are created through a repeatable process;
  • Docker images are published from releases, not from ad hoc local pushes;
  • external contributors know how to report issues and contribute;
  • main is protected from direct pushes.

Current State

Already in place:

  • MIT license.
  • Project version in pyproject.toml.
  • README with quick start, runtime choices, docs links, and CI badge.
  • MkDocs site and GitHub Pages workflow.
  • Main CI workflow with unit, integration, E2E, storage, container, and Hadolint checks.
  • Release Readiness workflow for Ruff, Pyright, Bruno file validation, strict docs build, and release tag/version validation.
  • CodeQL Analysis workflow for Python security scanning.
  • Dependency Review workflow for dependency vulnerability reporting.
  • Image Scan and SBOM workflow for Trivy and CycloneDX artifacts.
  • Real-Client MCP Smoke workflow on pull requests, pushes to main, weekly schedule, and manual dispatch.
  • Bruno black-box integration workflow for API/MCP smoke coverage.
  • Pytest and Bruno JUnit result publishing in CI.
  • Containerfile with OCI labels, non-root runtime, and CI smoke coverage.
  • Release/container publishing plan.
  • Promotion plan.

Missing or not yet enforced:

  • Docker Hub publish workflow.
  • Release workflow/checklist.
  • Version/tag validation.
  • CHANGELOG.md or chosen release notes source.
  • CONTRIBUTING.md.
  • CODE_OF_CONDUCT.md.
  • SECURITY.md.
  • Pull request template.
  • Issue templates.
  • Branch protection, required checks, Docker Hub secrets, and repository settings documented.
  • Branch protection policy that blocks direct pushes to main.
  • Required status checks selected in GitHub settings.
  • Repository topics and description applied in GitHub settings.

Release Scope

For v0.1.0, the release should promise the implemented backend/service capabilities only:

  • HTTP memory API.
  • Streamable HTTP MCP tools.
  • SQLite/LanceDB local default.
  • Postgres/PGVector runtime option.
  • Deterministic ingestion, search, retrieve, ask, facts, and generated summaries.
  • CLI and container runtime.
  • Bearer-token auth and project workspace boundaries.
  • Local-first, bring-your-own embedding model/storage posture.

Do not market unreleased browser extensions, hosted sync, UI dashboards, SDKs, or cloud service behavior as shipped release features.

P0: Repository Governance

These are required before the first release is promoted.

  • Document branch protection and required checks in repository_governance_settings.md.
  • Stop direct pushes to main.
  • Require pull requests for all changes after the release-readiness PR lands.
  • Require the main CI workflow before merge:
    • Unit and Integration Tests
    • E2E Scenario (Ollama)
    • Storage Config Variations
    • Storage Postgres Integration
    • Containerfile Lint
    • Container Build and Smoke
  • Require the docs build workflow before merge:
    • Build Documentation
  • Require the Bruno workflow when files under memory/**, tests/bruno/**, .github/workflows/bruno-integration.yml, pyproject.toml, or uv.lock change:
    • Bruno API/MCP Integration
  • Require real-client MCP smoke in PR CI while keeping individual client slots skip-safe when binaries or command templates are unavailable.
  • Require branch to be up to date before merge once queue/noise is manageable.
  • Decide whether signed commits are mandatory immediately. If yes, configure local signing before enabling enforcement.
  • Document the PR strategy in CONTRIBUTING.md:
    • one focused change per PR;
    • tests or docs for behavior changes;
    • no direct main pushes;
    • release changes go through a release PR.

P0: Community And Support Files

Add these root-level files before release:

  • CONTRIBUTING.md
    • local setup;
    • test commands;
    • documentation build commands;
    • PR expectations;
    • branch/commit policy;
    • release PR policy.
  • CODE_OF_CONDUCT.md
    • use a standard Contributor Covenant-style policy unless there is a reason to customize heavily.
  • SECURITY.md
    • supported versions;
    • how to report vulnerabilities privately;
    • expected response window;
    • reminder not to include secrets or private conversation data in reports.
  • .github/PULL_REQUEST_TEMPLATE.md
    • summary;
    • validation run;
    • docs impact;
    • security/privacy impact;
    • release note needed.
  • .github/ISSUE_TEMPLATE/bug_report.yml
  • .github/ISSUE_TEMPLATE/feature_request.yml
  • .github/ISSUE_TEMPLATE/config.yml

P0: Versioning And Release Notes

  • Decide release notes source:
    • GitHub generated release notes for the first release; or
    • committed CHANGELOG.md from the start.
  • Add a release checklist file, such as .github/RELEASE_CHECKLIST.md.
  • Add version validation:
    • release tag must be vMAJOR.MINOR.PATCH;
    • tag v0.1.0 must match pyproject.toml version = "0.1.0";
    • release workflow fails if tag and project version differ.
  • Define prerelease policy:
    • v0.1.0-rc.1 is allowed for release candidates;
    • prereleases do not update Docker latest.
  • Release notes must include:
    • one-paragraph project summary;
    • install/run commands;
    • Docker image tags and digest once publishing exists;
    • docs URL;
    • known limitations;
    • upgrade notes for config, storage schema, or container behavior.

P0: Docker Image Publishing

Use release_container_docs_plan.md for the detailed workflow. Minimum first release requirements:

  • Create Docker Hub repository for ai-memory-hub.
  • Add GitHub Actions secrets:
    • DOCKERHUB_USERNAME
    • DOCKERHUB_TOKEN
    • optional DOCKERHUB_NAMESPACE
  • Add .github/workflows/docker-publish.yml.
  • Trigger publish only on release.published and manual retry.
  • Manual retry checks out the requested release tag before building.
  • Build with Docker Buildx from the checked-in Containerfile.
  • Validate tag against pyproject.toml.
  • Block publishing on high/critical Trivy findings in the release image.
  • Push immutable version tags:
    • v0.1.0
    • 0.1.0
  • Push latest only for stable releases.
  • Add image digest to the workflow summary and release notes.
  • Keep PR and push builds as smoke-only, with no registry push.
  • Smoke-test the published Docker image by digest during the publish workflow before treating the release image as promoted.
  • Automatically update existing GitHub release notes with the image digest after the published-image smoke test passes.

P0: Documentation Readiness

  • README first screen clearly says what the project is, who it is for, and why local-first agent memory matters.
  • Quick start works from a clean checkout.
  • Docker/Compose quick start works from a clean checkout.
  • Deterministic quickstart checks and real-client smoke harness runs are covered by CI.
  • MCP client setup is reachable from README.
  • Security/auth guidance is reachable before LAN/container exposure docs.
  • Embedding model changes are documented as a DB-backed reindex workflow, with aim reindex recalculating vectors from stored metadata.
  • Release notes link to the generated docs site.
  • Known limitations are explicit:
    • no hosted memory service;
    • bring-your-own embedding model for production-quality retrieval;
    • browser extensions are future/separate repos;
    • UI and SDKs are future work.

P0: Release Candidate Drill

Before publishing v0.1.0, run one release-candidate rehearsal:

  1. Open a release-readiness PR.
  2. Confirm all required checks pass.
  3. Create a prerelease tag such as v0.1.0-rc.1.
  4. Publish a GitHub prerelease.
  5. Confirm Docker publish workflow produces only prerelease/version tags and not latest.
  6. Pull the image on a clean machine or clean container runtime.
  7. Run:
docker run --rm -p 127.0.0.1:8000:8000 <image>:v0.1.0-rc.1
curl -fsS http://127.0.0.1:8000/ready
  1. Run the README quick start from a clean checkout.
  2. Run the configured static-analysis finding review manually and revalidate until no open findings remain, with false positives or accepted risks documented.
  3. Fix any release-note, Docker, docs, setup, or finding-review issues before stable release.

P1: Supply Chain And Security Hardening

These are valuable but should not block v0.1.0 unless the image is promoted as production-ready.

  • Add Trivy image scan that blocks high/critical findings while preserving JSON/SBOM reports.
  • Block Docker release publishing on high/critical Trivy image findings.
  • Add blocking dependency vulnerability and license review.
  • Add SBOM generation for Docker images.
  • Add GitHub artifact attestations or provenance.
  • Add CodeQL for Python static security analysis.
  • Document best-effort release security scan findings in release_security_scan_notes.md.
  • Pin third-party GitHub Actions to commit SHAs.
  • Replace the Ollama install script with a pinned container image in E2E CI.
  • Enforce declared JSON Schema formats during conversation validation.
  • Pin Docker base/provider images by digest after the image cadence stabilizes.
  • Consider Cosign signing after the basic release process is stable.
  • Document image support lifecycle and security-fix policy.

P1: Repository Discoverability

  • Document GitHub repository description to match README positioning.
  • Document repository topics:
    • mcp
    • ai-agents
    • memory
    • rag
    • fastapi
    • pgvector
    • local-first
    • openai-compatible
  • Document repository description and topics in repository_governance_settings.md.
  • Apply repository description and topics in GitHub settings.
  • Pin the first release announcement issue or discussion after release.
  • Add a small demo GIF or terminal transcript when available.
  • Make sure the promotion plan has one launch-day post and one follow-up technical post ready.

First Release Checklist

Use this checklist for the release PR:

  • CONTRIBUTING.md added.
  • CODE_OF_CONDUCT.md added.
  • SECURITY.md added.
  • Issue templates added.
  • Pull request template added.
  • Docker publish workflow added.
  • Version/tag validation added.
  • Release checklist added.
  • README and docs reviewed.
  • Branch protection enabled.
  • Required checks selected.
  • main is green.
  • Manual static-analysis finding review revalidated with no open findings.
  • v0.1.0-rc.1 release candidate drill completed.
  • Stable v0.1.0 release published.
  • Docker image pull/run verified.
  • Release notes include image digest and docs URL.
  • Launch/promotion note posted.

Acceptance Criteria

The project is release-ready when:

  • no routine work requires direct pushes to main;
  • new contributors have clear conduct, contribution, security, issue, and PR guidance;
  • the release process can be repeated from a tag without local manual Docker publishing;
  • CI, docs, Bruno, and container smoke checks are visible and passing;
  • users can install or run from source and Docker using documented commands;
  • the first release notes accurately describe shipped behavior and known limits.