There are two ways to run the release: inside Docker (recommended) or natively.

This runs the release inside a container with all tools pre-installed. You only need Docker and credentials configured on the host.

1. Docker installed and running
2. Credentials configured (see Credential Setup below)
3. SSH agent running with a key that has push access to github.com:json-e/json-e

./release-docker.sh <version>   # without the `v` prefix

The script builds the Docker image (cached after first build), mounts your credentials read-only, forwards your SSH agent, and runs release.sh inside the container.

Run the release directly on your machine.

./release.sh <version>   # without the `v` prefix

The script runs comprehensive pre-flight checks before doing any work. If anything is missing or misconfigured, it reports all failures at once so you can fix everything in one pass.

npm login

Verify with npm whoami.

cargo login

This saves a token to ~/.cargo/credentials.toml. Alternatively, set the CARGO_REGISTRY_TOKEN environment variable.

Create a ~/.pypirc file:

[pypi]
username = __token__
password = pypi-<your-api-token>

Or set TWINE_USERNAME and TWINE_PASSWORD environment variables. Generate an API token at https://pypi.org/manage/account/token/.

Ensure you have an SSH key that can push to github.com:json-e/json-e. The release script auto-detects which git remote points to the json-e/json-e repository (it does not assume a specific remote name like origin or upstream).

ssh -T git@github.com   # should show your username

To publish, you must be a maintainer/owner on all three registries:

Having valid credentials is not enough — your account must have publish rights on the specific package.

1. Pre-flight checks — verifies all tools, credentials, Python version, repo state (clean tree, on main, tag doesn't exist yet)
2. Changelog — runs towncrier build to generate the changelog entry
3. Version bump — updates version in rs/Cargo.toml, js/package.json, and py/setup.py
4. Commit & tag — creates a v<version> commit and tag
5. Publish — uploads to crates.io, npm, and PyPI
6. Push — pushes the commit and tag to GitHub
7. Docs — rebuilds and deploys documentation via deploy-docs.sh

The release script publishes to registries sequentially (crates.io, then npm, then PyPI). If a publish step fails partway through:

• The git commit and tag already exist locally but may not have been pushed yet (push happens last).
• Some registries may have the new version while others don't. Most registries don't support unpublishing (npm has a 72-hour window, crates.io does not allow it at all, PyPI does not allow re-uploading the same version).
• Fix forward: resolve the issue and re-run the publish steps that failed, or cut a patch release if needed. The release script skips the changelog step if it detects the version already matches.