v0.1.0 release procedure

Copy Markdown View Source

This checklist is for maintainers publishing the first public lean_lsp Hex release. The goal is to publish v0.1.0 from a clean, current main branch with matching metadata, documentation, package contents, and downstream smoke-test coverage.

1. Prepare the release branch

  1. Fetch the latest repository state and confirm the release commit is based on the current main branch:

    git fetch origin main --tags
git switch main
git pull --ff-only origin main
git status --short

  2. Confirm that mix.exs, README.md, CHANGELOG.md, and the release readiness docs all describe version 0.1.0.

  3. Confirm that README.md still presents v0.1.0 as a foundation/runtime-preview release, not as a production-ready Lean LSP client.

  4. Confirm there are no uncommitted changes before the final validation pass.

2. Authenticate with Hex

Publishing requires a Hex account that has permission to publish lean_lsp.

mix hex.user auth
mix hex.user whoami

If Hex asks whether the package should be owned by an individual account or an organization, choose the owner intentionally before confirming the first publish. Do not use --yes for the final publish command; the final publish should remain an explicit maintainer action.

HEX_API_KEY is not required for the local manual release procedure. If a future automation flow uses HEX_API_KEY, keep it scoped to publish permissions and do not commit it to the repository.

3. Run pre-publish validation

Run the full project quality gate:

mix deps.get
mix check

Run the release-specific checks:

mix test
mix docs --warnings-as-errors
mix package.contents
LEAN_LSP_DOWNSTREAM_DOCKER=skip mix downstream.smoke
mix dependency.audit
mix publish.check

mix publish.check is intentionally non-publishing. It builds and unpacks the package, generates docs with warnings as errors, runs the downstream smoke test, and runs the Hex dry run with --dry-run --yes to avoid interactive prompts.

4. Inspect package contents

After mix package.contents or mix publish.check, inspect the unpacked package:

find _build/hex_publish_check -maxdepth 3 -type f | sort

The package should include the source files, README, CHANGELOG, license, and docs extras. It should not include _build, deps, doc, tmp, cover, .elixir_ls, priv/plts, compiled .beam files, tests, or CI-only scripts.

5. Publish to Hex

Immediately before publishing, confirm that lean_lsp is still available or is owned by the expected maintainer account.

Publish manually:

mix hex.publish

Review the package summary printed by Hex. Confirm the version, description, license, links, production dependencies, and package contents before answering the final prompt.

6. Verify Hex and HexDocs

After publishing, verify the public package page and generated documentation:

  • https://hex.pm/packages/lean_lsp
  • https://hexdocs.pm/lean_lsp
  • https://hexdocs.pm/lean_lsp/0.1.0

Check that Hex shows version 0.1.0, the package description, the Apache-2.0 license, the GitHub and HexDocs links, and only the intended production dependencies.

Check that HexDocs renders the README, CHANGELOG, release scope and stability notes, dependency audit, package contents note, runtime dependency policy, downstream smoke-test note, module responsibilities, and this release procedure.

Run the downstream smoke test against the published Hex package:

LEAN_LSP_DOWNSTREAM_DEP=hex LEAN_LSP_DOWNSTREAM_DOCKER=skip mix downstream.smoke

Use LEAN_LSP_DOWNSTREAM_DOCKER=required when Docker runtime verification is intended and Docker is available.

7. Tag and create the GitHub release

After the Hex package and HexDocs have been verified, tag the exact release commit:

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

Create the GitHub release from the tag:

gh release create v0.1.0 \
  --verify-tag \
  --title "v0.1.0" \
  --notes "Initial Hex foundation/runtime-preview release for LeanLsp."

The GitHub release notes should point users to CHANGELOG.md, Hex, and HexDocs. If the tag already exists, do not move it after publishing without also deciding how to handle the published Hex version.

8. Revert, update, or correct a bad first publish

If the first publish has a problem, act quickly and document what changed.

  • Documentation-only problems can usually be corrected with:

    mix hex.publish docs

  • A newly published package can be updated or reverted during Hex's first-release update window. For v0.1.0, use:

    mix hex.publish --revert 0.1.0

    Then fix the issue, rerun the full pre-publish validation, and publish again.

  • If the update window has closed, do not try to replace the published package. Prepare a follow-up version such as 0.1.1, update the changelog, and publish the correction as a new release.

After any revert or update, verify Hex, HexDocs, downstream dependency mode, the Git tag, and the GitHub release again.