A cargo workspace (docs) monorepo (info) hosting a collection of Rust utility crates.
Installation | Crates | Development | Docs
- Install Rust using
rustup(instructions) - Clone this repository:
$ git clone git@github.com:busticated/rusty.git && cd ./rusty - Setup local dev environment:
$ cargo xtask setup - View available commands:
$ cargo xtask help - Run the tests
$ cargo xtask test - Start Hacking!
- detect-newline-style
- Determine a string's preferred newline character
- node-js-release-info
- Asynchronously retrieve Node.js release info by version and platform from the downloads server
This repository contains a series of rust crates managed together as a cargo workspace (docs) with XTask. All essential commands are available via cargo xtask <script name> - e.g. cargo xtask todo. To view available commands, run: cargo xtask help
How to add a new crate
To add a new crate to the workspace, run cargo xtask crate:add and follow the prompts (add the --dry-run flag to test). Upon completion, your new crate will be available within ./crates/<your crate>
How to run tests
To run all tests for all crates:
cargo xtask test
To run unit tests for all crates:
cargo test --lib --all-features --workspace
To run unit tests for just your crate:
cargo test --lib --all-features --package <your crate's name>
To run integration tests for all crates:
cargo test --test integration --all-features --workspace
To run integration tests for just your crate:
cargo test --test integration --all-features --package <your crate's name>
To run tests for docs and examples in all crates:
cargo test --doc --all-features --workspace
To run tests for docs and examples in just your crate:
cargo test --doc --all-features --package <your crate's name>
To run a specific test:
cargo test --all-features <test name - e.g. "tests::it_fetches_node_js_release_info"> -- --exact
To output any println!() calls within tests, add the --nocapture flag after the -- option delimiter. Run cargo xtask help to see any other test-related commands that are available.
How to see code coverage stats
To see code coverage stats for all crates:
cargo xtask coverage --open
Run cargo xtask help to see any other coverage-related commands that are available.
How to check for spelling errors
To find spelling mistakes in source code and docs across the workspace, run:
cargo xtask spellcheck
Run cargo xtask help to see any other test-related commands that are available.
How to create docs
Public interfaces must be documented using inline annotations (docs).
Once you've added your inline documentation, run:
cargo xtask doc --open
Run cargo xtask help to see any other docs-related commands that are available.
How to format commits for changelogs
In order to support automated crate changelog updates, you will need to:
- Commit crate changes separately - e.g. run:
git add -p crates/<name>/*to stage files, then commit - Format your commit message like:
[<crate name>] <message>e.g.[node-js-release-info] update docs - Commit changes to the workspace itself (including the
xtaskcrate) separately without prefixing your commit message
Each crate has its own changelog (example). Upon releasing, each changelog will be updated with the changes made to that crate since its last release.
To view unpublished changelog entries for all crates, run:
cargo xtask changelog
Run cargo xtask help to see any other changelog-related commands that are available.
How to publish crates
To publish a crate to the crates.io registry, follow these steps:
- Checkout the
mainbranch:git checkout main - Run
cargo xtask crate:releaseand follow the prompts (add the--dry-runflag to test) - Verify all checks pass:
cargo xtask ci - Push to remote:
git push origin main --follow-tags
Each crate you select for publishing will be assigned its new version and all changes will be committed and tagged in git. The assigned tag will be formatted like name@version (e.g. detect-newline-style@1.0.0). After pushing to the remote, CI will execute the publishing steps and if all goes well, your crate will be available on crates.io.
How to view and add TODO source code comments
To see what TODOs exist across crates, run:
cargo xtask todo
When adding a TODO comment to your source code, format it like:
// TODO (<name>): <message>e.g.
// TODO (busticated): this is my example todo commentAny todo!() macros in the source code will also be reported.