Release Checklist

This page records the package publish order. It is intentionally conservative: publish lower-level packages first, then install and smoke the layers above them.

1. Registry and repository setup

Create the repository environments and registry trusted-publisher entries before the first live publish run. The configured PyPI and npm workflows use OIDC, so do not add long-lived PYPI_API_TOKEN or NPM_TOKEN repository secrets for the normal release path.

GitHub environments:

Environment	Workflows	Purpose
pypi-publish	.github/workflows/aidememo-python-publish.yml, .github/workflows/aidememo-agent-sdk-publish.yml, .github/workflows/hermes-aidememo-publish.yml	Approval gate for PyPI trusted publishing
npm-publish	.github/workflows/aidememo-napi-publish.yml	Approval gate for npm trusted publishing
github-pages	.github/workflows/pages.yml	OIDC-backed deployment of the validated Docusaurus build

Recommended protection: require a reviewer for the registry environments and restrict deployment branches/tags to the release branches or tags that the project uses.

Before the first documentation deployment, open Settings → Pages, set the publishing source to GitHub Actions, and restrict the generated github-pages environment to main. The Pages workflow keeps repository contents read-only during the build and grants pages: write plus id-token: write only to the deployment job. GitHub Pages content is publicly reachable even when a supported paid plan deploys from a private repository; do not enable it until the site is ready for public access.

PyPI trusted publishers:

Project	GitHub owner/repo	Workflow	Environment	Status
aidememo-python	taeyun16/aidememo	aidememo-python-publish.yml	pypi-publish	Workflow ready
aidememo-agent-sdk	taeyun16/aidememo	aidememo-agent-sdk-publish.yml	pypi-publish	Workflow ready
hermes-aidememo	taeyun16/aidememo	hermes-aidememo-publish.yml	pypi-publish	Workflow ready

npm trusted publishers:

Register each npm package with GitHub owner/repo taeyun16/aidememo, workflow aidememo-napi-publish.yml, and environment npm-publish:

1. aidememo-napi
2. aidememo-napi-darwin-arm64
3. aidememo-napi-darwin-x64
4. aidememo-napi-linux-arm64-gnu
5. aidememo-napi-linux-x64-gnu
6. aidememo-napi-win32-x64-msvc

Rust crates currently publish from an operator machine, not from GitHub Actions. Use cargo login or a local CARGO_REGISTRY_TOKEN when running cargo publish; do not add a repository secret unless a Rust publish workflow is introduced.

The Elixir NIF is currently documented as a local/path binding. There is no Hex publish workflow or repository HEX_API_KEY requirement yet; add those only if the project decides to publish aidememo_nif through Hex.

Optional runtime keys such as OPENAI_API_KEY are for local feature use (aidememo extract --llm) and are not release secrets.

2. Local preflight

Run the local release gate from a clean checkout:

scripts/release-preflight.sh

The same gate is also available as the manual GitHub workflow .github/workflows/release-preflight.yml. Use profile=local for the normal release-candidate pass. Use profile=full only when you also want the Rust package dry-run or Python/npm publish dry-runs, and turn those on explicitly with the workflow inputs.

This includes the version pins, changelog release gate, registry readiness, public portability, workflow syntax lint, docs feature coverage, docs-site build, binding smoke, agent SDK/Hermes wheel smoke, workflow smoke, and SDK promotion check.

The changelog release gate is offline and should pass after cutting the current release notes out of Unreleased:

mise run changelog-release-check
python3 scripts/changelog-release-check.py 0.1.0

It verifies that CHANGELOG.md has an empty [Unreleased] section, one dated current-version section immediately below it, and non-empty release-note content. Set AIDEMEMO_RELEASE_PREFLIGHT_CHANGELOG=0 only for focused non-release debugging.

The registry readiness gate is offline and should pass before creating or editing registry entries:

python3 scripts/registry-readiness-check.py

It verifies that PyPI trusted-publisher project names, workflow names, GitHub environments, npm root/platform package names, and this release document stay aligned. It also rejects first-party publish workflows that drift back to long-lived publish-token assumptions.

The public onboarding gates should also pass before pushing the release tag:

python3 scripts/public-portability-check.py
scripts/fresh-checkout-smoke.sh

The portability gate rejects developer-specific home paths in first-party tracked files. The fresh-checkout smoke is also available as .github/workflows/fresh-checkout-smoke.yml; it rebuilds from a copy without .git, target, or Node build output and runs the deterministic quickstart.

maturin is intentionally run through uvx using the pinned spec from mise.toml, not from whichever maturin happens to be on PATH.

The Python binding uses PyO3 0.29. Release smoke scripts prefer the same Python 3.13 interpreter used by CI, while accepting PyO3-supported local interpreters. To force a specific interpreter, set it explicitly:

AIDEMEMO_PYO3_PYTHON=python3.13 scripts/release-preflight.sh

For a full registry dry-run:

AIDEMEMO_RELEASE_PREFLIGHT_PROFILE=full scripts/release-preflight.sh 0.1.0

The full profile also runs the Rust publish dry-run readiness gate. Standalone use is:

scripts/cargo-package-readiness.sh

CI also runs the same gate in the cargo-package-readiness job. That PR guard enforces aidememo-core cargo publish --dry-run while keeping dependent Rust crates as the documented publish-order skip until aidememo-core exists on crates.io.

3. Release tag contract

The canonical source release tag is v<version>, so the first public release uses v0.1.0. Create it only after remote CI and the full release preflight pass on the exact commit that will be published:

git tag -a v0.1.0 -m "AideMemo 0.1.0"
git push origin v0.1.0

Package-specific tags such as aidememo-python-v0.1.0 and aidememo-napi-v0.1.0 are optional artifact or dry-run triggers. They do not replace the canonical v0.1.0 source tag. Real PyPI and npm publishes remain manual workflow dispatches with an exact version input and approval environment.

4. Rust crates

Publish in dependency order:

1. aidememo-core
2. aidememo-cli
3. aidememo-ffi, aidememo-napi, aidememo-nif, aidememo-python

aidememo-cli and all native bindings depend on aidememo-core, so their cargo publish --dry-run checks will fail against crates.io until aidememo-core is published at the matching version.

The readiness script runs cargo publish --dry-run for aidememo-core by default and records dependent Rust crates as a deliberate skip until that first publish-order blocker is removed. After aidememo-core is visible on crates.io at the matching version, run the full dependent check:

AIDEMEMO_CARGO_PACKAGE_CHECK_DEPENDENTS=1 scripts/cargo-package-readiness.sh

5. Python packages

Publish native bindings before composition packages:

1. aidememo-python
2. aidememo-agent-sdk
3. hermes-aidememo

Local Python payload checks:

mise run python-pack-smoke
mise run python-publish-dry-run
mise run agent-sdk-publish-dry-run
mise run hermes-publish-dry-run

Before the first PyPI release, user-facing docs should show checkout installs:

python -m pip install -e packages/aidememo-agent-sdk
python -m pip install -e plugins/hermes

After PyPI release, docs can promote:

python -m pip install aidememo-agent-sdk
python -m pip install "aidememo-agent-sdk[binding]"
python -m pip install hermes-aidememo

6. Node package

Publish the platform packages before the root wrapper:

1. aidememo-napi-* platform packages
2. aidememo-napi

Use each trusted-publisher workflow with the exact version input. The default workflow mode is dry-run:

1. .github/workflows/aidememo-python-publish.yml
2. .github/workflows/aidememo-agent-sdk-publish.yml
3. .github/workflows/hermes-aidememo-publish.yml

7. Post-release checks

Before the registries are live, the post-release smoke can run in plan mode and print the exact install checks it will perform:

scripts/public-registry-smoke.sh

After each registry publish, run verify mode:

AIDEMEMO_PUBLIC_REGISTRY_SMOKE_MODE=verify scripts/public-registry-smoke.sh

The same check is available as the manual GitHub workflow .github/workflows/public-registry-smoke.yml. Keep mode=plan before the registries are live, then run the exact released version with mode=verify after publishing. The workflow exposes per-registry toggles so a partial publish can verify only the registry that changed.

This installs aidememo-cli, aidememo-agent-sdk, aidememo-agent-sdk[binding], hermes-aidememo, and aidememo-napi from public registries into temporary environments and imports / runs the installed packages. Use AIDEMEMO_PUBLIC_REGISTRY_SMOKE_* toggles to narrow the check when only one registry was published.

Then update README and docs to remove "from checkout until release" caveats for the packages that are actually available from public registries.