Releasing
Releasing
Section titled “Releasing”Sephera currently has two release surfaces:
- crates.io publishing for
cargo install sephera - binary GitHub Releases for users who want a prebuilt download
Publishable crates
Section titled “Publishable crates”Sixteen crates are published, in a dependency order computed from the manifests.
sephera_tools is internal-only and is the only member with publish = false,
which is also why it is the only one with no documentation field.
The order, from a real run:
1. sephera_core 2. sephera_compression 3. sephera_ignore 4. sephera_scan 5. sephera_context 6. sephera_symbols 7. sephera_graph_cpp 8. sephera_graph_go 9. sephera_graph_java10. sephera_graph_javascript11. sephera_graph_python12. sephera_graph_rust13. sephera_runtime14. sephera_graph15. sephera_mcp16. sepheraGet the current list at any time:
python scripts/check_publish_order.py --planWhy the order is computed and not written down
Section titled “Why the order is computed and not written down”cargo publish -p X resolves X’s dependencies from crates.io, so a path
dependency that has never been published fails with no matching package named Y
unless it is redirected back to the checkout. That redirect is a
--config patch.crates-io.Y.path=... for every crate beneath X — 64 of them
across the sixteen crates.
A --config naming a crate that is not a dependency is silently ignored. A
hardcoded list is therefore wrong invisibly, and the error it produces names a
dependency of the crate being published rather than the crate missing from the
list. The workflow this project had before the split listed three crates and two
patches, and failed with no matching package named sephera_compression found —
which reads like a missing crate and is actually a missing entry.
So both the order and the flags come from scripts/check_publish_order.py, and
that script both verifies them (CI) and executes them (release).
The patches also make the order look unnecessary: cargo publish would succeed
for a crate whose dependencies are not published yet, because they are read from
the checkout. What it would not do is produce an installable release — the
uploaded Cargo.toml names sephera_compression = "0.7.1", and a consumer has
nothing but the registry to resolve that against. The wait for each crate in the
index is what makes the published set resolvable.
crates.io workflow
Section titled “crates.io workflow”The repository includes a manual GitHub Actions workflow:
.github/workflows/publish.ymlUse it through workflow_dispatch. It takes two inputs:
version— the version to publish, which must matchCargo.tomldry_run— on by default, so the first thing a run does is prove the plan works rather than upload. A release is the unchecked box.
The workflow:
- checks the requested version against the workspace version and refuses a mismatch
- runs formatting, clippy (workspace and fuzz), tests, and the docs build
- runs
python scripts/check_publish_order.py --publish, which publishes all sixteen crates in order, waiting for each to appear in the crates.io index before the next one starts
It expects:
- a protected
releaseenvironment - a
CRATES_IO_TOKENsecret in thatreleaseenvironment, with publish access
If the workflow editor shows a warning such as Context access might be invalid: CRATES_IO_TOKEN, that usually means the secret is not visible to static analysis from the repository alone. The workflow still works once CRATES_IO_TOKEN is created in the protected release environment.
The token is read from the environment rather than passed as an argument, because a token on a command line lands in the process table and in the shell history.
cargo publish refuses a dirty tree. In a dry run that refusal is lifted with
--allow-dirty, so the plan can be exercised mid-edit; a real upload still
refuses, and does.
Binary release workflow
Section titled “Binary release workflow”Binary archives are handled by a separate GitHub Actions workflow:
.github/workflows/release.ymlThis workflow uses a hybrid trigger:
workflow_dispatchfor manual alpha or prerelease buildspushon stablev*tags for production GitHub Releases
It does not create tags for you. Maintainers are expected to create the tag first, then either push it for an automatic stable release or select the matching ref/tag manually through workflow_dispatch.
The binary release workflow:
- reruns formatting, linting, tests, and docs build in a preflight job
- builds
sepherafor four desktop targets - packages each target as an archive containing the binary and
LICENSE - generates
SHA256SUMS.txt - creates or updates the matching GitHub Release and uploads the assets
Binary targets
Section titled “Binary targets”x86_64-pc-windows-msvcas.zipx86_64-unknown-linux-muslas.tar.gzx86_64-apple-darwinas.tar.gzaarch64-apple-darwinas.tar.gz
Binary artifact naming
Section titled “Binary artifact naming”Each binary archive follows the same naming convention:
sephera-{tag}-{target}.zipsephera-{tag}-{target}.tar.gzExample:
sephera-v0.3.0-x86_64-unknown-linux-musl.tar.gzcrates.io checklist
Section titled “crates.io checklist”Before publishing:
- bump the workspace version in
Cargo.toml— every crate inherits it throughversion.workspace = true, so one edit covers all sixteen - run formatting, clippy, tests, and the docs build
- run
python scripts/check_publish_order.pyand confirm all sixteen crates package and verify - run
python scripts/check_publish_order.py --publishonce with the default dry run — this is the same thing CI’spublish_dry_runjob checks, but it also exercises the ordering the real release uses - trigger
publish.ymlwithdry_runoff andversionset to the workspace version
Binary release checklist
Section titled “Binary release checklist”Before pushing a stable v* tag or triggering a manual prerelease:
- make sure the release ref is committed and pushed
- create the release tag first
- verify the release workflow will build from the same ref as the tag
- confirm the generated asset names match the
sephera-{tag}-{target}convention - verify
SHA256SUMS.txtis attached alongside the archives
Verification commands
Section titled “Verification commands”cargo fmt --all --checkcargo clippy --workspace --all-targets --all-features -- -D warningscargo clippy --manifest-path fuzz/Cargo.toml --all-targets -- -D warningscargo test --workspacenpm run docs:buildpython scripts/check_publish_order.pycargo build --locked --release --bin sepheracheck_publish_order.py covers what the two cargo publish --dry-run lines it
replaces did, for all sixteen crates rather than three.
Packaging notes
Section titled “Packaging notes”sepherais the user-facing install cratesephera_guiis the graphical front-end, and ispublish = false— see below- the fifteen library crates are the split of what
sephera_coreused to be, and each carries a README saying whether a reader should install it sephera_toolsstays unpublished, and is the only other one withpublish = falsepublish.ymlis for crates.io publishing, whilerelease.ymlis for prebuilt GitHub release assets- the crates.io READMEs are separate from the GitHub landing README so each surface can stay focused on its own audience
The GUI is not published
Section titled “The GUI is not published”sephera_gui has publish = false, and that is a consequence of being a binary
rather than a library. Publishing it would pull winit, a graphics backend and a
font stack into every tree that wanted a line count, and crates.io would gain a
crate whose only entry point is a window.
It also has its own rust-version rather than the workspace’s 1.85: eframe
0.36 declares 1.95, and a manifest that claims otherwise is promising something
it cannot keep. CI does not gate MSRV, so this diverges without breaking
anything — but it is a real divergence and it is recorded rather than hidden.
The GUI has its own cargo profile
Section titled “The GUI has its own cargo profile”release.yml builds the CLI with the workspace release profile and the GUI
with release-gui. The CLI’s profile is lto = "fat" and codegen-units = 1
because a hot loop crossing a crate boundary is what it is; a GUI is idle in its
event loop and has none. The commands, from a clean target directory:
cargo build --release -p sephera # fat LTO, unchangedcargo build -p sephera_gui --profile release-gui # thin LTOcargo build --release -p sephera_gui # for comparisonMeasured from clean, each built once:
| what | time | directory | binary |
|---|---|---|---|
| CLI, fat LTO | 2m 30s | 0.66 GiB | 14.7 MB |
| GUI, thin LTO | 2m 57s | 1.29 GiB | 16.7 MB |
| GUI, fat LTO | 4m 19s | 1.24 GiB | 14.4 MB |
So thin LTO saves 32% of the build for 2.3 MB of binary, which is the right way round for a window that waits for clicks.
Every crate carries a README
Section titled “Every crate carries a README”Each of the fifteen library manifests declares readme = "README.md", and
cargo publish refuses a crate whose readme is missing with readme README.md does not appear to exist. Publishing is the only thing that names that file, so
nothing else in the tree caught it — the same shape as the dead-code trap in
AGENTS.md, a declaration with nothing behind it.
check_publish_order.py writes any missing README and prints which ones it
wrote. That step prints every publishable crate has one on a healthy tree.
docs.rs links
Section titled “docs.rs links”Every publishable crate’s manifest points documentation at
https://docs.rs/<crate>. A crate that has never been published returns a 404
there, because docs.rs builds a page from a published version rather than from a
repository. The thirteen linked crates 404 until the release that introduces
them lands.
That makes a documentation field a claim the release has to honour, which is
worth knowing the next time a crate is added to the workspace without a
corresponding entry in the release plan.