Releases are cut from main by a maintainer with Hex and GitHub credentials.

Gate

The independent YAML checks require test-only ruamel.yaml==0.18.16. Install it in a Python virtual environment and set FORMATA_YAML_REFERENCE_PYTHON to that environment's interpreter, or install the pinned version for python3. CI and Release install the same pin; it is not a Formata runtime dependency. Python 3.11+ is also required for the existing independent TOML tomllib checks.

All of these must pass on the commit to release:

mix deps.get
mix format --check-formatted
(
  erlang_build_dir=$(mktemp -d)
  trap 'rm -r "$erlang_build_dir"' EXIT
  erlc -Werror +warn_deprecated_catch -I include -o "$erlang_build_dir" src/*.erl
)
mix compile --warnings-as-errors --force
mix test
mix docs
mix hex.build

mix test includes the ported upstream suites alongside the module tests under test/formata/, the TOML 1.0.0 toml-test suite, and the required JSON-Schema-Test-Suite cases for Draft 7 and Draft 2020-12. Run it on the oldest supported Elixir (1.18) as well; CI does.

The separate erlc gate compiles every shipped Erlang runtime source into a fresh temporary directory, so cached BEAM files cannot skip it. -Werror treats Erlang warnings as errors; +warn_deprecated_catch enables the OTP 28 opt-in warning that OTP 29 enables by default. CI retains both supported Elixir versions and runs this gate on each, as does the release workflow. Run the same command from an unpacked package to check consumer sources.

Also smoke-test the built package from an isolated consumer:

mix hex.build --unpack -o /tmp/formata-unpacked
# in a fresh project: {:formata, path: "/tmp/formata-unpacked"}; mix deps.get; run an example
# (mix deps.get must fetch nothing: Formata has no runtime dependencies)

Automated release

The Release workflow (.github/workflows/release.yml, manual dispatch with version and git_ref) does steps 2–5 below: it sets @version, runs the gate, commits chore(release): vX.Y.Z and pushes it with the annotated tag, publishes to Hex with the HEX_API_KEY secret, and creates the GitHub release from the CHANGELOG.md entry plus generated notes. Add the changelog entry first; the workflow fails without it. Reruns are safe: an existing tag is only accepted on the exact commit being released, and an already published Hex version or existing GitHub release is skipped.

gh workflow run release.yml -f version=X.Y.Z -f git_ref=main

Manual steps

  1. Update @version in mix.exs and the CHANGELOG.md entry.
  2. Run the gate.
  3. Commit, then tag: git tag -a vX.Y.Z -m "vX.Y.Z"; push main and the tag. Never move or overwrite an existing tag or release.
  4. Publish: mix hex.publish (package and docs).
  5. Create the GitHub release from the tag with the changelog entry: gh release create vX.Y.Z --title vX.Y.Z --notes-file <notes>.
  6. Verify https://hex.pm/packages/formata and https://hexdocs.pm/formata.