Skip to content

refactor(crates): publish library as evt3, CLI as evt3-cli, and make the project findable - #6

Merged
muthmann merged 3 commits into
mainfrom
feat/crate-naming-and-discoverability
Aug 12, 2026
Merged

refactor(crates): publish library as evt3, CLI as evt3-cli, and make the project findable#6
muthmann merged 3 commits into
mainfrom
feat/crate-naming-and-discoverability

Conversation

@muthmann

@muthmann muthmann commented Aug 12, 2026

Copy link
Copy Markdown
Owner

Makes the project installable and findable. It was effectively invisible: the
GitHub repo had no description and no topics, the CLI was not on crates.io at
all, evt3-core was stuck at 0.2.0 while the workspace moved to 0.3.0, and the
PyPI page was a stub that told visitors to build from source.

Breaking change

The decoder library is published as evt3 instead of evt3-core:

- evt3-core = "0.2"
+ evt3 = "0.3"
- use evt3_core::Evt3Decoder;
+ use evt3::Evt3Decoder;

Source directories are unchanged. The CLI is published as evt3-cli and still
installs a binary named evt3, so command-line usage does not change.

The short name went to the library, not the CLI. A binary-only crate has no lib
target, so cargo add evt3 succeeds silently and only fails later at compile
time with E0433 — whose help text then suggests the command the user already
ran. Registry names cannot be reassigned, so this had to be settled before the
first publish. Rationale is recorded in ADR 0005.

Result:

Command Gets you
cargo add evt3 the Rust library
cargo install evt3-cli the CLI (binary evt3)
pip install evt3 the Python package

evt3 now means the library on both registries.

Publishing was also broken

Two things would have failed cargo publish regardless of naming:

  • evt3-cli declared six crates.io keywords; the registry permits five.
  • Path dependencies carried no version, which crates.io rejects. The internal
    dependency is now declared once in [workspace.dependencies].

The release workflow never touched crates.io, which is why the library went
stale. A publish-crates job now publishes evt3, waits for the index, then
publishes evt3-cli — the order matters, since the CLI cannot be packaged
until the library is in the index. Both steps treat an already-published
version as success, so re-running a tag recovers.

Discoverability

The root README led with "EVT3 Decoder" and never mentioned Metavision, DVS,
neuromorphic, or event-based vision. Rewritten around the terms people search,
with crates.io/docs.rs/pyversions badges.

evt3-python/README.md — the PyPI landing page — was a 1587-character stub
recommending a source build. Replaced with a full page using absolute links,
since PyPI does not render relative ones.

Repository description, homepage, and 20 topics were set directly on GitHub and
are already live.

Verification

Check Result
cargo fmt --check, clippy -D warningshdf5) clean
Rust lib tests 28 pass / 30 with hdf5
Integration tests 8 pass / 16 with hdf5, incl. real-file HDF5
Doctests 2 pass
MSRV cargo check -p evt3-python on Rust 1.83 pass
Python 3.9 / 3.13 / 3.14t free-threaded pass
CLI vs C++ reference identical MD5, 1.64x faster
cargo publish -p evt3 --dry-run pass
Markdown links and anchors, repo-wide all resolve
Every documented cargo … -p <pkg> command executed, all work

Verified on macOS/arm64 only; Ubuntu, Windows, and Python 3.10–3.12 are covered
by CI on this PR.

Not included

The version bump belongs in the release commit, per RELEASING.md. After merge,
workspace.package.version, workspace.dependencies.evt3.version, and
evt3-python/pyproject.toml go to 0.4.0, ## [Unreleased] becomes
## [0.4.0] - <date>, and the tag triggers the publish.

BREAKING CHANGE: the decoder library is published as `evt3` instead of
`evt3-core`. Replace `evt3-core = "0.2"` with `evt3 = "0.3"` and
`use evt3_core::...` with `use evt3::...`. Source directories are unchanged.

The short name went to the library rather than the CLI. A binary-only crate
has no lib target, so `cargo add evt3` would succeed silently and only fail
later at compile time with E0433, whose help text then suggests the command
the user already ran. Registry names cannot be reassigned, so the choice had
to be made before the first publish.

Also fixes two blockers that would have failed `cargo publish`:

- `evt3-cli` declared six crates.io keywords; the registry permits five.
- Path dependencies carried no version. The internal dependency is now
  declared once in `[workspace.dependencies]` with an explicit version.

The `evt3-python` lib target is renamed to `evt3_python` so it does not
collide with its own `evt3` dependency. maturin takes the Python module name
from `tool.maturin.module-name`, so the built module is unchanged.

Records the decision in ADR 0005.
The release workflow built binaries and wheels and pushed to PyPI, but never
touched crates.io. `evt3-core` therefore stayed at 0.2.0 while the workspace
moved to 0.3.0, and the CLI was never published at all.

Adds a `publish-crates` job that publishes the `evt3` library, waits for it to
appear in the index, then publishes `evt3-cli`. The order matters: the CLI
depends on the library by version and cannot be packaged until the library is
in the index. Both steps treat an already-published version as success so a
re-run of a tag recovers instead of failing.

Requires the `CARGO_REGISTRY_TOKEN` repository secret.
The root README led with "EVT3 Decoder", a term with almost no search volume
outside people who already know the format name, and never mentioned
Metavision, DVS, neuromorphic, or event-based vision. Rewrites the heading and
intro around what people actually search for, and adds crates.io, docs.rs, and
Python version badges.

The PyPI page was worse: `evt3-python/README.md` was a 1587-character stub
that told visitors to build from source and never mentioned `pip install
evt3`. Replaces it with a full landing page covering install, quick start,
bounded-memory batches, streaming, triggers, and AugurRS. All links are
absolute because PyPI does not render relative links.

Both READMEs now document the three install paths consistently:
`pip install evt3`, `cargo install evt3-cli`, and `cargo add evt3`.
@muthmann
muthmann force-pushed the feat/crate-naming-and-discoverability branch from 9c46146 to 3f7fccb Compare August 12, 2026 15:07
@muthmann
muthmann merged commit fcd8203 into main Aug 12, 2026
18 checks passed
@muthmann
muthmann deleted the feat/crate-naming-and-discoverability branch August 12, 2026 15:12
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.

1 participant