https://github.com/brson/cargo-crusader
Test the downstream impact of Rust crate changes before publishing
https://github.com/brson/cargo-crusader
Last synced: 10 months ago
JSON representation
Test the downstream impact of Rust crate changes before publishing
- Host: GitHub
- URL: https://github.com/brson/cargo-crusader
- Owner: brson
- Created: 2015-08-02T21:23:42.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2018-04-22T03:50:47.000Z (about 8 years ago)
- Last Synced: 2025-08-30T15:35:46.318Z (10 months ago)
- Language: Rust
- Homepage:
- Size: 32.2 KB
- Stars: 58
- Watchers: 8
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Cargo Crusader
Hark, Rust crate author! The battle for Rust's reputation as *The Most
Reliable Software Platform Ever* is here, and nobody is free of
responsibility. The future of Rust, dear Rustilian, is in your hands.
Join the **Cargo Crusade** and bring the [Theory of Responsible API
Evolution][evo] to the non-believers.
Cargo Crusader is a tool to help crate authors evaluate the impact of
future API changes on downstream users of that crate before they are
published to [crates.io].
[evo]: https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md
[crates.io]: http://crates.io
[semver]: http://semver.org/
# How?
When you run `cargo-crusader` from the source directory of your
published crate, Crusader asks crates.io for all of its reverse
dependencies - *published crates that DEPEND ON YOU*. It then
downloads each of them, and builds them: first against your crate as
currently published, then against your local work-in-progress
(i.e. the next version you are going to publish). It then reports
differences in behavior.
# Getting Started
**IMPORTANT SECURITY WARNING: This program executes arbitrary
untrusted code downloaded from the Internet. You are strongly
recommended to take your own sandboxing precautions before running
it.**
First, download and build Cargo Crusader, and put the `cargo-crusader`
command in your `PATH` environment variable:
```sh
$ git clone https://github.com/brson/cargo-crusader
$ cd cargo-crusader
$ cargo build --release
$ export PATH=$PATH:`pwd`/target/release/
```
Now change directories to your source and run `cargo-crusader`:
```sh
$ cargo-crusader
crusader: downloading reverse deps for hyper
crusader: 10 reverse deps
crusader: testing crate aloft
crusader: testing crate austenite
crusader: result 1 of 10, aloft 0.3.1: broken
crusader: testing crate bare
crusader: result 2 of 10, austenite 0.0.1: broken
crusader: testing crate catapult
crusader: result 3 of 10, bare 0.0.1: broken
crusader: testing crate chan
crusader: result 4 of 10, catapult 0.1.2: broken
crusader: testing crate chatbot
crusader: result 5 of 10, chan 0.1.14: passed
crusader: testing crate click_and_load
crusader: result 6 of 10, chatbot 0.2.2: regressed
crusader: testing crate coinbaser
crusader: result 7 of 10, click_and_load 0.0.1: broken
crusader: testing crate doapi
crusader: result 8 of 10, coinbaser 0.1.0: regressed
crusader: testing crate ease
crusader: result 9 of 10, doapi 0.1.0: broken
crusader: result 10 of 10, ease 0.2.1: regressed
passed: 1
regressed: 3
broken: 6
error: 0
full report: ./crusader-report.html
```
A full run will take quite a while. After its done it will print a
summary, as well as produce an HTML file containing the full results,
including all the compiler output for each test.
Tests result in four possible statuses: 'passed', if the reverse
dependency built both before and after the upgrade; 'regressed', if it
built before but not after; 'broken', if it didn't even build before
upgrading; and 'error', for internal Crusader errors.
# Future improvements
Presently Crusader will override reverse dependencies with your local
revision *even if the version they requested is not semver compatible
with your work-in-progress*. Crusader might first verify whether or
not the WIP qualifies as a semver-valid upgrade.
Testing upstream as well - Crusader could ask for all the WIP branches
of your dependencies and then override your build to see if upcoming
changes are going to break your crate.
Sandboxing.
# License
MIT/Apache-2.0 is the official license of both The Rust Project and The Cargo Crusade.