Repository navigation
Releasing
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.
| 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.
Pushing a signed v* tag starts four workflows at once:
-
release.ymlchecks the tag's signature against.github/allowed_signersonmain, and thatCargo.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, ifCRATES_PUBLISHistrue, itscrates-iojob publishes them in dependency order and checks each one's checksum on crates.io against the attested package. -
release-python.ymlbuilds the wheels and the sdist, waits for that GitHub release, then publishes to PyPI ifPYPI_PUBLISHistrue. -
release-npm.ymlbuilds and tests the package, waits for the release, then publishes to npm ifNPM_PUBLISHistrue. -
release-capi.ymlbuilds 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.
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.
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=tagTo have a second maintainer approve each publish as well, add a required reviewer under Settings → Environments → release.
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.)
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.
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 |
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-publishgh 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/parsecFor 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 1For 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.
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 4Wait for all four to go green (gh run watch RUN_ID --repo parsec-html/parsec).
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.0tag -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.
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
donecrates.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.
- 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 NAMEfor each crate (with a token that has the yank scope), andnpm 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.
-
The tag check fails. Nothing was published. Delete the tag (
git -C ~/Documents/GitHub/parsec push origin :refs/tags/v0.1.0andgit -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.shat 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.
Parsec is Apache-2.0 and not yet released; these pages describe main. Found something wrong here? Open an issue or ask in Discussions.
Repository · Issues · Discussions · Roadmap · Security policy · Licence