refactor(crates): publish library as evt3, CLI as evt3-cli, and make the project findable - #6
Merged
Merged
Conversation
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
force-pushed
the
feat/crate-naming-and-discoverability
branch
from
August 12, 2026 15:07
9c46146 to
3f7fccb
Compare
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.
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-corewas stuck at 0.2.0 while the workspace moved to 0.3.0, and thePyPI page was a stub that told visitors to build from source.
Breaking change
The decoder library is published as
evt3instead ofevt3-core:Source directories are unchanged. The CLI is published as
evt3-cliand stillinstalls 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 evt3succeeds silently and only fails later at compiletime with
E0433— whose help text then suggests the command the user alreadyran. Registry names cannot be reassigned, so this had to be settled before the
first publish. Rationale is recorded in ADR 0005.
Result:
cargo add evt3cargo install evt3-clievt3)pip install evt3evt3now means the library on both registries.Publishing was also broken
Two things would have failed
cargo publishregardless of naming:evt3-clideclared six crates.io keywords; the registry permits five.dependency is now declared once in
[workspace.dependencies].The release workflow never touched crates.io, which is why the library went
stale. A
publish-cratesjob now publishesevt3, waits for the index, thenpublishes
evt3-cli— the order matters, since the CLI cannot be packageduntil 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 stubrecommending 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
cargo fmt --check, clippy-D warnings(±hdf5)hdf5hdf5, incl. real-file HDF5cargo check -p evt3-pythonon Rust 1.83cargo publish -p evt3 --dry-runcargo … -p <pkg>commandVerified 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, andevt3-python/pyproject.tomlgo to 0.4.0,## [Unreleased]becomes## [0.4.0] - <date>, and the tag triggers the publish.