Skip to content

RELEASING.md

Latest commit

 

History

History
87 lines (69 loc) · 3.82 KB

RELEASING.md

File metadata and controls

87 lines (69 loc) · 3.82 KB

Releasing MemPalace

Pre-release checklist

Run from the repo root before cutting a release tag.

Verify mempalace-mcp entry point alignment

The plugin configs reference mempalace-mcp as the MCP server command, which resolves to a console script declared under [project.scripts] in pyproject.toml. If these disagree, pip install mempalace ships a plugin config pointing at a binary that was never installed — exactly what broke v3.3.2 (#1093).

grep -r mempalace-mcp pyproject.toml .claude-plugin .codex-plugin

Expected on a healthy develop (post-#340) — one line per file:

pyproject.toml:mempalace-mcp = "mempalace.mcp_server:main"
.claude-plugin/plugin.json:      "command": "mempalace-mcp"
.codex-plugin/plugin.json:      "command": "mempalace-mcp"
.claude-plugin/.mcp.json:    "command": "mempalace-mcp"

If pyproject.toml has no match, stop — the entry point is missing and any fresh pip install will ship a broken plugin config. Investigate whether the release branch was cut before #340 landed on develop.

Publishing to PyPI

Releases publish automatically via the publish.yml workflow, using PyPI Trusted Publishing (OIDC). There is no API token stored anywhere — GitHub mints a short-lived identity at upload time. The workflow fires when a GitHub Release is published, builds the sdist + wheel, and pauses for manual approval on the pypi environment before uploading.

One-time setup (owners only)

Done once per project; both steps require PyPI owner / GitHub admin rights.

  1. PyPI trusted publisher — on PyPI, go to Manage project mempalace → Publishing → Add a trusted publisher and enter exactly:

    Field Value
    Owner MemPalace
    Repository name mempalace
    Workflow filename publish.yml
    Environment name pypi

  2. GitHub environment — in the repo, Settings → Environments → New environment named pypi. Add yourself (and any other release approvers) under Required reviewers. This is the manual gate the workflow waits on before the upload step runs.

Cutting a release

  1. Bump the version in all five sources on develop so version-guard.yml stays green (it is the single source of truth at mempalace/version.py, mirrored in pyproject.toml, .claude-plugin/marketplace.json, .claude-plugin/plugin.json, and .codex-plugin/plugin.json).
  2. Land everything for the release on develop, then merge develop → main. Releases publish only from main — the workflow refuses any tag whose commit is not an ancestor of main. Don't commit the bump directly to main: it bypasses branch protection and leaves develop behind.
  3. Run the entry-point alignment check above.
  4. On GitHub, Releases → Draft a new release:
    • Target: main
    • Tag: vX.Y.Z (must equal mempalace/version.py; the workflow and version-guard.yml both reject a mismatch)
    • Write the release notes, then Publish release.
  5. The publish.yml run validates the tag (on main, matches the manifest), builds, and then waits for approval on the pypi environment. Approve it to upload to PyPI. Watch the run land the new version on https://pypi.org/project/mempalace/.

To stage a release candidate without shipping to end users, tag a semver pre-release (vX.Y.Z-rc1) — version-guard.yml skips the strict manifest match for pre-release tags. (Note: a published GitHub Release still triggers publish.yml; use a draft release, or a plain pushed tag, for dry runs you don't want uploaded.)