Repository navigation
build: 0.1.0 had no crates to publish and no path to publish them - #122
Merged
Merged
Conversation
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.
jamesconwaydev
enabled auto-merge (squash)
November 20, 2026 00:57
foothillsdigital
approved these changes
Nov 20, 2026
foothillsdigital
left a comment
Collaborator
There was a problem hiding this comment.
Checked c6f779b.
Crates.
scripts/package-twice.sh HEADhere gives the six packages identical both times.- Each has a real
LICENSE(11,357 bytes) andNOTICE(3,442), not the symlinks, plus a README.parsec-html-cssalso keepsdata/webref/LICENSE. - The facade's manifest has
cssoff andencoding,urlandxpathon. cargo check -p parsec-htmlpasses with no default features, and with each feature alone.pub use html::*can't be shadowed by the explicit modules, since the core only exportscssandtokenizeras modules, and the CSS crate comes in asstylesheet.cargo clippy --workspace --all-targets -D warningsis clean,cargo test --workspacepasses (318), and so does-p parsec-html --all-features. CI is green.
Release gating. I traced each path:
- A pushed unsigned tag:
tagfails,buildskips,crates-ioskips through its impliedsuccess(), 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:
tagstill runs, since its condition is the ref, not the event. - A manual run on a branch:
tag,publishandcrates-ioall skip, andbuildruns alone, as intended. crates-iousesid-token: writeandcontents: readonly, in thereleaseenvironment, 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:
- Compare before uploading, not after.
cargo publishpackages 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. Runningcargo package --workspace --exclude parsec-capi --lockedat the top of the step and comparing all six with$RUNNER_TEMP/distbefore the loop would stop a mismatch, such as fromstablemoving between thebuildandcrates-iojobs, before anything is published. Then SECURITY.md's "crates.io has the same bytes as the release" is a guarantee, not something checked afterwards. - 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,isDraftforgithub-actions[bot]and not a draft costs one line, and makes the gate mean "release.yml passed" rather than "a release exists".release-capi.ymlcould take the same line.
Approving.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 waspublish = 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 forrelease.yml's signature check, so oncePYPI_PUBLISHorNPM_PUBLISHwas 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 stillparsec), andcrates/parsec-htmlis a new crate namedparsec-htmlthat re-exports it at the top:parsec::cssselectors, DOM)parsec-html-coreparsec::encodingencodingparsec-html-encodingparsec::urlurlparsec-urlparsec::xpathxpathparsec-xpathparsec::stylesheetcssparsec-html-cssparsec::csswas already the selector engine (synced), so the CSS crate isparsec::stylesheet.use parsec::...code doesn't change, and nothing undercrates/parsec/srcdoes either. Dependents nameparsec-html-coreand get the sameparseclibrary; that's one line in each ofbench/, 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
LICENSEandNOTICEsymlinked in, since Apache-2.0 wants both to go with the code and the packages had neither. The CSS, encoding and URL packages leave outtests/, whose vendored suites were most of each package; the suites still run in the repo. Package sizes:.crateWorkflows.
scripts/package-twice.shpackages all six (cargo 1.90+ packages a workspace's crates against each other before they're published), andrelease.ymlattests and attaches all of them.release.yml's tag job also checksCargo.toml's version is the tag's.crates-iojob inrelease.ymlruns after the build, in thereleaseenvironment, whenCRATES_PUBLISHistrue. It gets a token fromrust-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.ymlandrelease-npm.ymlwait forrelease.yml's GitHub release before publishing, asrelease-capi.ymlalready did, and skip versions already up (skip-existing,npm view). Their timeouts are 45 minutes, since most of it is waiting.Docs.
CHANGELOG.mdfor 0.1.0, by module, with PR links. The README's "Using it" now hascargo add parsec-htmlwith the features,pip install parsec-html,npm install parsec-htmland 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.mdcovers 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
Releasingpage 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) andcargo deny checkpass.cargo publish --dry-run --workspace --exclude parsec-capiverifies and "uploads" all six in order: core, url, css, encoding, xpath, parsec-html. On its own,cargo publish --dry-run -p parsec-xpathfails with "no matching package namedparsec-html-corefound", as it should until core is up. That's why CI uses the workspace form.scripts/package-twice.shgives the same six SHA-256s on cargo 1.100.0 and 1.99.1, and the same ascargo package --workspacein a checkout with submodules.cargo package -p parsec-html-coreon its own, which is what the publish job runs, matches too.--features css), and it builds with--no-default-features --features xpath.cargo doc -p parsec-htmlhas no warnings with or without features.cargo check --locked, and bench's lock resolves with--locked.actionlintandshellcheck scripts/package-twice.share 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
releaseenvironment, deployable fromv*tags only:parsec-html-core,parsec-html-encoding,parsec-url,parsec-xpathandparsec-html-css, asparsec-htmlalready has. Use a 1-day token with publish-new scope forparsec-*from https://crates.io/settings/tokens/new; the loop is on the Releasing page. Thencargo logoutand revoke the token.https://crates.io/crates/NAME/settingsfor all six crates, add a trusted publisher: GitHub, ownerparsec-html, repoparsec, workflowrelease.yml, environmentrelease.parsec-html, ownerparsec-html, repoparsec, workflowrelease-python.yml, environmentrelease.npm publisha 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, environmentrelease, 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.Each release
mainis green.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.gh release download v0.1.0 --repo parsec-html/parsec --dir ~/parsec-0.1.0, thengh attestation verifyon each.crate(--signer-workflow parsec-html/parsec/.github/workflows/release.yml) and C package (release-capi.yml). Compare crates.io's checksums withSHA256SUMS, and do acargo add parsec-html@0.1.0/pip install parsec-html==0.1.0/npm install parsec-html@0.1.0smoke test. All of it is on the Releasing page.