release

name	release
description	Cut a release of the free maplibre-geoman / mapbox-geoman packages (bump versions, finalize CHANGELOG, tag, publish to npm). Use when asked to release, publish, cut a version, or prep a release (e.g. "release 0.8.4", "publish a prerelease").

Release process

This monorepo publishes from a single workspace version kept in lockstep across four manifests: the root package.json, packages/core, packages/maplibre, and packages/mapbox. The two published packages are @geoman-io/maplibre-geoman-free and @geoman-io/mapbox-geoman-free, released to the public npm registry (registry.npmjs.org) with provenance.

Publishing is done by the Release GitHub Actions workflow (.github/workflows/release.yml), triggered by pushing a v*.*.* tag (or via workflow_dispatch). A release is two steps: prep (a commit on master) then tag (which publishes).

0. Preconditions

• You are releasing from master, it's up to date (git pull), and the working tree is clean.
• The changes being released are merged and CI on master is green.
• Decide the version, following the existing line (e.g. 0.8.4). A prerelease contains -alpha/-beta/-rc and publishes under the beta dist-tag instead of latest.

1. Prep commit

git checkout master && git pull

# Bump root + core + maplibre + mapbox package.json (one version, all four).
# Always use the script — never hand-edit versions — so the manifests stay in
# lockstep (the release workflow rejects a mismatch).
node scripts/bump-version.mjs <version>      # e.g. 0.8.4

pnpm install is not required for a version bump: pnpm-lock.yaml does not embed workspace package versions, so there is no lockfile change. (Only run an install if you also changed dependencies.)

Then edit CHANGELOG.md (Keep a Changelog format — the release workflow extracts the notes for this version straight from here):

• Rename the existing ## [Unreleased] heading to ## [<version>] - <YYYY-MM-DD> (today's date).
• Add a fresh empty ## [Unreleased] section directly above it.
• Fill in the entries under ### Added / ### Changed / ### Fixed, describing the released state from the user's perspective. Link merged PRs where useful, e.g. ([#208](https://github.com/geoman-io/maplibre-geoman/pull/208)). Drop WIP-only notes; call out default-behavior changes under ### Changed.

Commit (do not push yet):

git add -A
git commit -m "chore(release): prep v<version>

<one short paragraph on what's in this release>"

The pre-commit hook runs scripts/validate-workspace.mjs, which enforces that all four manifests carry the same version — if it fails, re-run the bump script.

2. Push + tag (this publishes)

git push origin master

git tag v<version>           # tag name MUST be v<version>, e.g. v0.8.4
git push origin v<version>   # pushing the tag triggers release.yml → npm publish

The tag's version must equal the root package.json version, or the workflow's validate job fails on purpose.

3. Verify

gh run list --workflow=release.yml --limit 1     # find the Release run
gh run watch <run-id>                            # follow it to completion

The workflow runs validate (version + workspace-version checks, workspace:validate), build-and-test (pnpm install --frozen-lockfile, formatter, typecheck:all, lint:all, test:unit, package both variants, api:check), the full Playwright e2e matrix (maplibre + mapbox), then creates the GitHub Release (notes pulled from CHANGELOG.md) and publishes both packages to npm — --access public --provenance, under latest for a stable version or --tag beta for a prerelease. Confirm the run is green and the new version shows up on npm.

Notes / gotchas

• Don't hand-edit versions — always use scripts/bump-version.mjs so root + core + maplibre + mapbox stay in lockstep (the workspace validator and the workflow's version check both reject a mismatch).
• No lockfile edit for a plain version bump (the lockfile doesn't embed workspace versions), so no pnpm install is needed for the bump.
• The CHANGELOG section heading must be ## [<version>] - <date> so the release-notes extractor finds it; an empty/missing section yields empty GitHub-release notes.
• To re-run a failed publish, fix forward and push a new patch tag — do not move or delete an existing published tag.
• The workflow can also be run from the Actions tab (workflow_dispatch) with an explicit version + prerelease flag, without pushing a tag.