🦀 Publishing My First Rust Crate

So, I've published my first Rust crate.
This post is a brief summary of my experience going through the process. There is no TLDR, because the whole post a TLDR, essentially.😛

🤗 Positive

• The dev process is super smooth with tests that just work out of the box and require zero additional configuration.
• There are official guidelines documenting the API design best practices.
• Doc comments can (and should) include example code snippets that also serve as additional tests for your crate's public API.
• The process of publishing is well-documented.
• Documentation is automatically generated for every published crate by docs.rs.
• The release ritual can be automated with cargo-release.

😢 Negative

• Need to keep a lot of things in mind to make sure your crate has great interoperability with the existing Rust ecosystem, e.g. because of the orphan rule the users of your crate won't be able to implement the traits defined in std or serde for the types from your crate, so you have to decide which ones it makes sense to implement and provide that implementation yourself.
• It is currently not possible to specify that a certain version of a crate implementing some cargo-* subcommand must be installed when working on my crate. It's quite limiting, especially coming from JS where you can explicitly declare a cli package as a dependency of your own package and use it in build scripts, etc.

🤷🏻‍♂️ Confusing

• Where should I put the main documentation for my crate? Should it be README.md or a //! doc comment in src/lib.rs? Eventually, I ended up placing the crate documentation in lib.rs and using cargo-readme to extract it into README.md whenever I publish a new release. It's cool that it's possible, but it's also an additional build step I have to care about. Don't know how people solve it usually, so please comment if you have a better workflow.

👨🏻‍🏫 Recommendations

• Use clippy with a config, as annoying as you can still handle. Mine is:
  

  #![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)]
  

• Use cargo-release and setup pre-release hooks and replacements.

• Use cargo-readme for extracting the crate documentation from src/lib.rs into README.md, thus avoiding duplicating it manually.

🔮 Final thoughts

Coming from a JS background and only recently starting dabbling in Rust I'd say the overall experience working on a Rust library is far more enjoyable than what you are going through authoring an npm package.
This is, mostly, because the language itself comes with a bigger part of the tooling that you need to be productive. I really appreciate things like the built-in testing framework and excellent workflow around crate's documentation. At the same time, it doesn't feel like the cargo ecosystem is fully matured yet, and certain things I'm used to having accessible in npm world are missing (or maybe I'm just not aware of the alternatives).

Anyways, I'd be happy to read your take on how to setup and maintain a crate in the comments, let me know what you think.

Comments

[Elliot Jackson]

Hey, congrats on publishing your first crate! Just chiming in to say that with Rust, documentation is definitely better off being in the .rs files themselves because of the awesomeness that is docs.rs. The official Rust book has a section on doc comments. For an example of a very well documented crate, check out regex.