Skip to content

Releasing

James Conway edited this page Nov 20, 2026 · 1 revision

This is how a Parsec release goes out, from an empty registry to cargo add parsec-html. Most of it happens once, before 0.1.0; after that, a release is a version bump, a changelog entry and a signed tag.

On this page: What gets published · How the workflows fit · Before the first release · Every release · Check what went out · After the release · If something fails

Every command runs from your home folder as written. Paths are absolute and gh gets --repo, so nothing depends on where your shell is.

What gets published

Where Name What it is
crates.io parsec-html The crate people depend on. use parsec::..., with encoding, url and xpath on by default and css off.
crates.io parsec-html-core The parser, selectors and DOM, synced from Netweir.
crates.io parsec-html-encoding, parsec-url, parsec-xpath, parsec-html-css The modules behind the features.
PyPI parsec-html Wheels for CPython 3.9 to 3.15, free-threaded too, and an sdist.
npm parsec-html The WebAssembly build, for browsers and Node.
GitHub release parsec-capi-VERSION-TARGET.tar.gz / .zip The C library, header, pkg-config and CMake files, for five targets.

The C API isn't on crates.io: it's a C library, and its users want the built .so, .dylib or .dll, not a Rust crate.

Why six crates and not one? The modules all depend on the parser, so the parser can't depend on them, and its source comes from Netweir, so it can't carry the re-exports either. parsec-html is a thin crate on top that re-exports the lot.

How the workflows fit

Pushing a signed v* tag starts four workflows at once:

  • release.yml checks the tag's signature against .github/allowed_signers on main, and that Cargo.toml's version is the tag's. It packages all six crates twice from fresh checkouts, fails if the two differ by a byte, attests them and makes the GitHub release. Then, if CRATES_PUBLISH is true, its crates-io job publishes them in dependency order and checks each one's checksum on crates.io against the attested package.
  • release-python.yml builds the wheels and the sdist, waits for that GitHub release, then publishes to PyPI if PYPI_PUBLISH is true.
  • release-npm.yml builds and tests the package, waits for the release, then publishes to npm if NPM_PUBLISH is true.
  • release-capi.yml builds the C packages, waits for the release, then attests them and attaches them to it.

No release, no publishing: a tag with a bad signature or the wrong version stops at the first job, and the other three time out waiting after 30 minutes without publishing anything. All three publish jobs run in the release environment and use trusted publishing, so no registry token is stored in GitHub. Each one skips a version that's already up, so a failed run can be run again.

Before the first release

Do these once. The trusted-publisher steps have a deadline on npm (see step 5), so take them in this order, with the npm one on the day you tag.

1. Make the release environment

Only v* tags can deploy to it:

gh api -X PUT repos/parsec-html/parsec/environments/release \
  -F "deployment_branch_policy[protected_branches]=false" \
  -F "deployment_branch_policy[custom_branch_policies]=true"
gh api -X POST repos/parsec-html/parsec/environments/release/deployment-branch-policies \
  -f name='v*' -f type=tag

To have a second maintainer approve each publish as well, add a required reviewer under Settings → Environments → release.

2. Put the five new crates on crates.io

crates.io won't let trusted publishing create a crate: the first version of each has to come from an API token. parsec-html already has its 0.0.0 placeholder (published 18 November 2026). The other five need the same, so that 0.1.0 of every crate comes from the release workflow, attested and checked.

Make a token at crates.io/settings/tokens/new: name parsec placeholders, expiry 1 day, scope publish-new only, crates parsec-*. Then:

cargo login    # paste the token
for c in parsec-html-core parsec-html-encoding parsec-url parsec-xpath parsec-html-css; do
  curl -sf -o /dev/null -A "parsec-html release" "https://crates.io/api/v1/crates/$c" && continue    # there already
  d="$HOME/parsec-placeholders/$c"
  mkdir -p "$d/src" && : > "$d/src/lib.rs"
  printf '[package]\nname = "%s"\nversion = "0.0.0"\nedition = "2024"\nlicense = "Apache-2.0"\ndescription = "A placeholder for part of Parsec, the HTML toolkit. Use parsec-html."\nrepository = "https://github.com/parsec-html/parsec"\n' "$c" > "$d/Cargo.toml"
  cargo publish --manifest-path "$d/Cargo.toml" --allow-dirty || break
done
cargo logout
rm -rf "$HOME/parsec-placeholders"

Then revoke the token on the same page. crates.io limits how fast new crates can be made. If one is refused as too many, the loop stops there: wait as long as the error says, cargo login again and rerun it, and it skips the crates already up.

Note

The other way round, publishing 0.1.0 itself from your machine with cargo publish --workspace --exclude parsec-capi from ~/Documents/GitHub/parsec, also works: the release workflow skips versions crates.io has. But those five would then be built on your machine, not attested by the workflow, and the checksum check would fail unless your build is byte for byte the release's. The placeholders avoid both.

To give the other maintainer the same rights on every crate:

for c in parsec-html parsec-html-core parsec-html-encoding parsec-url parsec-xpath parsec-html-css; do
  cargo owner --add foothillsdigital "$c"
done

(That needs a token with the change-owners scope; each invite has to be accepted on crates.io.)

3. Add the trusted publisher on crates.io, for each crate

For each of parsec-html, parsec-html-core, parsec-html-encoding, parsec-url, parsec-xpath and parsec-html-css, open https://crates.io/crates/NAME/settings, choose Add under Trusted Publishing, and fill in:

Field Value
Publisher GitHub
Repository owner parsec-html
Repository name parsec
Workflow filename release.yml
Environment release

The direct links: parsec-html · parsec-html-core · parsec-html-encoding · parsec-url · parsec-xpath · parsec-html-css

One token from the workflow covers every crate set up this way.

4. Add a pending publisher on PyPI

parsec-html doesn't exist on PyPI yet, so this is a pending publisher, which creates the project on its first upload. At pypi.org/manage/account/publishing, under GitHub:

Field Value
PyPI Project Name parsec-html
Owner parsec-html
Repository name parsec
Workflow name release-python.yml
Environment name release

5. Put parsec-html on npm, and add its trusted publisher

npm, too, needs the package to exist before it can trust a workflow, and a new trusted publisher has to make its first publish within 2 days or it expires. So publish a placeholder now, and add the publisher on the day you tag.

The placeholder (npm asks for your 2FA code):

mkdir -p "$HOME/parsec-npm-placeholder"
printf '{\n  "name": "parsec-html",\n  "version": "0.0.0",\n  "description": "A placeholder for Parsec, the HTML parser. 0.1.0 is the first release.",\n  "license": "Apache-2.0",\n  "repository": { "type": "git", "url": "git+https://github.com/parsec-html/parsec.git" }\n}\n' > "$HOME/parsec-npm-placeholder/package.json"
npm login
npm publish "$HOME/parsec-npm-placeholder" --access public
rm -rf "$HOME/parsec-npm-placeholder"

On tag day, at npmjs.com/package/parsec-html/access, under Trusted Publisher, choose GitHub Actions:

Field Value
Organization or user parsec-html
Repository parsec
Workflow filename release-npm.yml
Environment name release
Allowed actions tick npm publish (the workflow publishes directly, not staged)

Or the same from the command line, with npm 11.15 or newer:

npm trust github parsec-html --file release-npm.yml --repo parsec-html/parsec --env release --allow-publish

6. Turn publishing on

gh variable set CRATES_PUBLISH --repo parsec-html/parsec --body true
gh variable set PYPI_PUBLISH --repo parsec-html/parsec --body true
gh variable set NPM_PUBLISH --repo parsec-html/parsec --body true
gh variable list --repo parsec-html/parsec

Every release

1. Check it's ready

For 0.1.0, that's #32: its blockers closed, and the benchmark ahead of Lexbor on every page.

gh issue view 32 --repo parsec-html/parsec
gh run list --repo parsec-html/parsec --branch main --workflow ci.yml --limit 1

2. Set the version and the changelog

For 0.1.0 this is done: every version is already 0.1.0. For the next one, change version in ~/Documents/GitHub/parsec/Cargo.toml ([workspace.package]), the version = "…" requirements in crates/*/Cargo.toml, bindings/python/Cargo.toml and bindings/wasm/npm/package.json, and add the release to CHANGELOG.md, in a pull request like any other.

3. Try the release without publishing

A manual run does everything but the tag check and the publishing:

for w in release.yml release-python.yml release-npm.yml release-capi.yml; do
  gh workflow run "$w" --repo parsec-html/parsec --ref main
done
sleep 10
gh run list --repo parsec-html/parsec --event workflow_dispatch --limit 4

Wait for all four to go green (gh run watch RUN_ID --repo parsec-html/parsec).

4. Tag and push

From an up-to-date main, with the SSH key listed in .github/allowed_signers:

git -C ~/Documents/GitHub/parsec switch main
git -C ~/Documents/GitHub/parsec pull --ff-only
git -C ~/Documents/GitHub/parsec -c gpg.format=ssh -c user.signingkey="$HOME/.ssh/id_ed25519.pub" tag -s v0.1.0 -m "Parsec 0.1.0"
git -C ~/Documents/GitHub/parsec -c gpg.ssh.allowedSignersFile="$HOME/Documents/GitHub/parsec/.github/allowed_signers" tag -v v0.1.0
git -C ~/Documents/GitHub/parsec push origin v0.1.0

tag -v should print Good "git" signature for …. Then watch the four runs:

gh run list --repo parsec-html/parsec --commit "$(git -C ~/Documents/GitHub/parsec rev-parse 'v0.1.0^{commit}')"

If the release environment has a required reviewer, each publish job waits for an approval on its run page.

Check what went out

The files on the release, and their provenance:

gh release download v0.1.0 --repo parsec-html/parsec --dir "$HOME/parsec-0.1.0"
for f in "$HOME"/parsec-0.1.0/*.crate; do
  gh attestation verify "$f" --repo parsec-html/parsec \
    --signer-workflow parsec-html/parsec/.github/workflows/release.yml
done
for f in "$HOME"/parsec-0.1.0/parsec-capi-*.tar.gz "$HOME"/parsec-0.1.0/parsec-capi-*.zip; do
  gh attestation verify "$f" --repo parsec-html/parsec \
    --signer-workflow parsec-html/parsec/.github/workflows/release-capi.yml
done

crates.io's checksums against the release's SHA256SUMS (the workflow checks this too):

for c in parsec-html parsec-html-core parsec-html-encoding parsec-url parsec-xpath parsec-html-css; do
  echo "$(curl -s -A "parsec-html release" "https://crates.io/api/v1/crates/$c/0.1.0" | jq -r .version.checksum)  $c-0.1.0.crate"
done | sort -k2 | diff - <(sort -k2 "$HOME/parsec-0.1.0/SHA256SUMS") && echo "crates.io matches"

Each registry, from a clean project:

cargo new --vcs none "$HOME/parsec-try" && cargo add --manifest-path "$HOME/parsec-try/Cargo.toml" parsec-html@0.1.0 --features css
cat > "$HOME/parsec-try/src/main.rs" <<'EOF'
fn main() {
    let doc = parsec::parse("<ul><li class=hit>one<li>two</ul>", false);
    let hits = parsec::css::SelectorList::parse("li.hit").unwrap().select(&doc, doc.root());
    println!("{}", doc.text(hits[0]));
}
EOF
cargo run -q --manifest-path "$HOME/parsec-try/Cargo.toml"    # one

python3 -m venv "$HOME/parsec-venv" && "$HOME/parsec-venv/bin/pip" install -q parsec-html==0.1.0
"$HOME/parsec-venv/bin/python" -c 'from parsec_html import HTMLParser; print(HTMLParser("<ul><li class=hit>one<li>two</ul>").css_first("li.hit").text())'    # one

mkdir -p "$HOME/parsec-npm-try" && npm install -s --prefix "$HOME/parsec-npm-try" parsec-html@0.1.0
(cd "$HOME/parsec-npm-try" && node --input-type=module -e 'import { parse } from "parsec-html"; console.log(parse("<ul><li class=hit>one<li>two</ul>").selectFirst("li.hit").textContent)')    # one
(cd "$HOME/parsec-npm-try" && npm audit signatures)

rm -rf "$HOME/parsec-try" "$HOME/parsec-venv" "$HOME/parsec-npm-try" "$HOME/parsec-0.1.0"

Also look at docs.rs/parsec-html, which builds a few minutes after the publish, with every feature on.

After the release

  • Turn on Require trusted publishing in each crate's settings on crates.io, so a leaked token can't publish a version.
  • Yank the 0.0.0 placeholders, so nobody picks one by accident: cargo yank --version 0.0.0 NAME for each crate (with a token that has the yank scope), and npm deprecate parsec-html@0.0.0 "Use 0.1.0 or later".
  • On the wiki: Home and Getting started say Parsec isn't on crates.io, and Changelog has the release under "Unreleased". Change all three.
  • Post the release in Discussions (Announcements), and close #32.

If something fails

  • The tag check fails. Nothing was published. Delete the tag (git -C ~/Documents/GitHub/parsec push origin :refs/tags/v0.1.0 and git -C ~/Documents/GitHub/parsec tag -d v0.1.0), fix what it says, and tag again.
  • A publish job fails after others succeeded. Fix the cause (usually a trusted publisher field that doesn't match), then gh run rerun RUN_ID --failed --repo parsec-html/parsec. Versions already up are skipped.
  • The crates.io checksum check fails. crates.io has a package that isn't the release's: someone published by hand, or the package isn't reproducible. Don't yank in a hurry; compare the two with scripts/package-twice.sh at the tag first.
  • A version is wrong once it's up. crates.io, PyPI and npm never let a version number be used twice. Yank it and release the next patch version.

Clone this wiki locally