Skip to content

build: 0.1.0 had no crates to publish and no path to publish them - #122

Merged
jamesconwaydev merged 3 commits into
mainfrom
release-0.1.0-prep
Nov 20, 2026
Merged

jamesconwaydev merged 3 commits into
mainfrom
release-0.1.0-prep

Conversation

@jamesconwaydev

Copy link
Copy Markdown
Collaborator

Problem

0.1.0 (#32) couldn't go out as designed. The design is one crate to depend on, parsec-html, with encoding, URL, XPath and CSS behind features. But those modules all depend on the parser, so the parser's package can't depend back on them, and its source is synced from Netweir, so it can't hold the re-exports either. Every crate was publish = false, and nothing in the workflows put anything on crates.io.

The PyPI and npm release workflows had a hole too: they run on any v* tag push and never waited for release.yml's signature check, so once PYPI_PUBLISH or NPM_PUBLISH was on, an unsigned tag would have published. And there was no changelog, and the README only installed from git.

Change

Crates. The parser's package is renamed parsec-html-core (its library is still parsec), and crates/parsec-html is a new crate named parsec-html that re-exports it at the top:

Module Feature Default Crate
top level (parser, parsec::css selectors, DOM) always parsec-html-core
parsec::encoding encoding on parsec-html-encoding
parsec::url url on parsec-url
parsec::xpath xpath on parsec-xpath
parsec::stylesheet css off parsec-html-css

parsec::css was already the selector engine (synced), so the CSS crate is parsec::stylesheet. use parsec::... code doesn't change, and nothing under crates/parsec/src does either. Dependents name parsec-html-core and get the same parsec library; that's one line in each of bench/, the bindings and the fuzz manifests, and their lock files. The C API stays off crates.io: it's a C library, shipped with each release.

All six are 0.1.0 with versioned path deps, docs.rs links, a readme, and LICENSE and NOTICE symlinked in, since Apache-2.0 wants both to go with the code and the packages had neither. The CSS, encoding and URL packages leave out tests/, whose vendored suites were most of each package; the suites still run in the repo. Package sizes:

Crate Files Unpacked .crate
parsec-html 8 57 KiB 20 KiB
parsec-html-core 166 1.9 MiB 357 KiB
parsec-html-css 47 1.8 MiB 321 KiB (was 903 KiB)
parsec-html-encoding 11 103 KiB 32 KiB (was 556 KiB)
parsec-url 17 381 KiB 103 KiB (was 610 KiB)
parsec-xpath 28 196 KiB 54 KiB

Workflows.

  • scripts/package-twice.sh packages all six (cargo 1.90+ packages a workspace's crates against each other before they're published), and release.yml attests and attaches all of them.
  • release.yml's tag job also checks Cargo.toml's version is the tag's.
  • A new crates-io job in release.yml runs after the build, in the release environment, when CRATES_PUBLISH is true. It gets a token from rust-lang/crates-io-auth-action (v1.0.6, pinned by SHA), publishes in dependency order, skips versions crates.io already has, and fails if crates.io's checksum isn't the attested package's.
  • release-python.yml and release-npm.yml wait for release.yml's GitHub release before publishing, as release-capi.yml already did, and skip versions already up (skip-existing, npm view). Their timeouts are 45 minutes, since most of it is waiting.
  • CI's reproducible job packages all six with verification on and compares them with the script's.

Docs. CHANGELOG.md for 0.1.0, by module, with PR links. The README's "Using it" now has cargo add parsec-html with the features, pip install parsec-html, npm install parsec-html and the C packages from the release, all marked "from 0.1.0" with the git routes kept until then. The module paths it names are the umbrella's now. SECURITY.md covers the supported versions (0.1.x) and how to check all six crates, the crates.io checksums, and PyPI's and npm's attestations.

The wiki gets a new Releasing page and a sidebar link, to push after this merges.

Refs #32. It stays open until the release is out.

Tests

  • cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (no failures) and cargo deny check pass.
  • cargo publish --dry-run --workspace --exclude parsec-capi verifies and "uploads" all six in order: core, url, css, encoding, xpath, parsec-html. On its own, cargo publish --dry-run -p parsec-xpath fails with "no matching package named parsec-html-core found", as it should until core is up. That's why CI uses the workspace form.
  • scripts/package-twice.sh gives the same six SHA-256s on cargo 1.100.0 and 1.99.1, and the same as cargo package --workspace in a checkout with submodules. cargo package -p parsec-html-core on its own, which is what the publish job runs, matches too.
  • The README's Rust snippets run against the umbrella (--features css), and it builds with --no-default-features --features xpath. cargo doc -p parsec-html has no warnings with or without features.
  • The Python and WASM bindings cargo check --locked, and bench's lock resolves with --locked.
  • actionlint and shellcheck scripts/package-twice.sh are clean.

Release checklist

Everything below is for the maintainer. The full version, with every command, is on the wiki's new Releasing page.

Once, before 0.1.0

  • Make the release environment, deployable from v* tags only:
    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
  • crates.io: trusted publishing can't create a crate, so publish a 0.0.0 placeholder for parsec-html-core, parsec-html-encoding, parsec-url, parsec-xpath and parsec-html-css, as parsec-html already has. Use a 1-day token with publish-new scope for parsec-* from https://crates.io/settings/tokens/new; the loop is on the Releasing page. Then cargo logout and revoke the token.
  • crates.io: on https://crates.io/crates/NAME/settings for all six crates, add a trusted publisher: GitHub, owner parsec-html, repo parsec, workflow release.yml, environment release.
  • PyPI: at https://pypi.org/manage/account/publishing/, add a pending publisher: project parsec-html, owner parsec-html, repo parsec, workflow release-python.yml, environment release.
  • npm: the package has to exist first, so npm publish a 0.0.0 placeholder (on the Releasing page). On tag day, since an unused config expires after 2 days, add the trusted publisher at https://www.npmjs.com/package/parsec-html/access: GitHub Actions, parsec-html / parsec, release-npm.yml, environment release, with npm publish allowed. From the command line: npm trust github parsec-html --file release-npm.yml --repo parsec-html/parsec --env release --allow-publish.
  • 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

Each release

  • Release 0.1.0 #32's blockers are closed and main is green.
  • Do a dry run of all four with 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, and wait for green.
  • Tag and push:
    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
  • Verify: gh release download v0.1.0 --repo parsec-html/parsec --dir ~/parsec-0.1.0, then gh attestation verify on each .crate (--signer-workflow parsec-html/parsec/.github/workflows/release.yml) and C package (release-capi.yml). Compare crates.io's checksums with SHA256SUMS, and do a cargo add parsec-html@0.1.0 / pip install parsec-html==0.1.0 / npm install parsec-html@0.1.0 smoke test. All of it is on the Releasing page.
  • After: turn on "Require trusted publishing" on each crate, yank or deprecate the 0.0.0 placeholders, update the wiki's Home, Getting started and Changelog, post in Discussions, and close Release 0.1.0 #32.

The design is one crate to depend on, parsec-html, with the other
standards behind features. But encoding, CSS and XPath all depend on the
parser, so the parser's package can't depend back on them, and its
source is synced from Netweir, so it can't hold the re-exports anyway.

The parser's package is now parsec-html-core, and crates/parsec-html is
a new crate named parsec-html that re-exports it at the top, with
parsec::encoding, parsec::url and parsec::xpath on by default and
parsec::stylesheet behind `css` (parsec::css is already the selector
engine). Its library is still `parsec`, so `use parsec::...` code is
unchanged; dependents name parsec-html-core under the same library name.

Every crate but the C API is publishable at 0.1.0, with path
dependencies versioned, docs.rs links, and LICENSE and NOTICE linked in,
since Apache-2.0 asks for both to travel with the code. The CSS,
encoding and URL packages leave out tests/, whose vendored suites were
most of each package; the suites still run from the repository.
release.yml checked the tag's signature and packaged one crate; nothing
put any crate on crates.io. release-python.yml and release-npm.yml run
on the same tag push but never waited for that check, so an unsigned
v* tag would have published to PyPI and npm once their variables were
on.

package-twice.sh now packages every published crate, with cargo
packaging them against each other before any is on crates.io, and the
release attests and attaches all six. A new crates-io job in release.yml
runs after the build, behind the `release` environment and the
CRATES_PUBLISH variable, and gets a token by trusted publishing. It
publishes in dependency order, skips a version crates.io already has,
and fails if crates.io's checksum isn't the attested package's.

The PyPI and npm publish jobs wait for release.yml's GitHub release, as
release-capi.yml does, and skip a version that's already up, so a failed
run can be run again. CI's reproducible job packages the workspace with
verification on, which builds each package against the others, and
compares it with the script's.
CHANGELOG.md records 0.1.0 by module, with the PRs behind each part.
The README's "Using it" gives cargo add with the features, pip install,
npm install and the C packages from the release, all marked from 0.1.0
with the git routes kept until then, and the module paths it names are
the umbrella crate's (parsec::encoding, parsec::stylesheet, ...).
SECURITY.md says 0.1.x gets fixes and how to check the six crates, the
crates.io checksums, and PyPI's and npm's attestations.

@foothillsdigital foothillsdigital left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked c6f779b.

Crates.

  • scripts/package-twice.sh HEAD here gives the six packages identical both times.
  • Each has a real LICENSE (11,357 bytes) and NOTICE (3,442), not the symlinks, plus a README. parsec-html-css also keeps data/webref/LICENSE.
  • The facade's manifest has css off and encoding, url and xpath on.
  • cargo check -p parsec-html passes with no default features, and with each feature alone.
  • pub use html::* can't be shadowed by the explicit modules, since the core only exports css and tokenizer as modules, and the CSS crate comes in as stylesheet.
  • cargo clippy --workspace --all-targets -D warnings is clean, cargo test --workspace passes (318), and so does -p parsec-html --all-features. CI is green.

Release gating. I traced each path:

  • A pushed unsigned tag: tag fails, build skips, crates-io skips through its implied success(), no release is made, and the PyPI and npm jobs time out without publishing. That closes the hole the description names.
  • A manual run on a tag ref: tag still runs, since its condition is the ref, not the event.
  • A manual run on a branch: tag, publish and crates-io all skip, and build runs alone, as intended.
  • crates-io uses id-token: write and contents: read only, in the release environment, with the auth action pinned by SHA, and no stored token.

Two hardening suggestions, neither blocking, since CRATES_PUBLISH is off until you turn it on:

  1. Compare before uploading, not after. cargo publish packages from the checkout and uploads, and only then is crates.io's checksum compared with the attested one. A mismatch is caught but can't be undone, since crates.io only yanks. Running cargo package --workspace --exclude parsec-capi --locked at the top of the step and comparing all six with $RUNNER_TEMP/dist before the loop would stop a mismatch, such as from stable moving between the build and crates-io jobs, before anything is published. Then SECURITY.md's "crates.io has the same bytes as the release" is a guarantee, not something checked afterwards.
  2. Have the PyPI and npm jobs check who made the release. The wait loop takes any release for the tag. Releases are made by people with write access, the same people who could change the workflow, so this isn't a real gap today. But checking gh release view "$GITHUB_REF_NAME" --json author,isDraft for github-actions[bot] and not a draft costs one line, and makes the gate mean "release.yml passed" rather than "a release exists". release-capi.yml could take the same line.

Approving.

@jamesconwaydev
jamesconwaydev merged commit 2061932 into main Nov 20, 2026
39 checks passed
@jamesconwaydev
jamesconwaydev deleted the release-0.1.0-prep branch November 20, 2026 01:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Release 0.1.0

2 participants