`cargo-crev` - User Guide, differential reviews and 0.8 release

Hi,

After a period of inactivity, partially caused by other projects, and partially by almost zero user growth and retention, I’ve picked up continuing working on cargo-crev (an implementation of crev code review system idea for Rust).

I’m currently focused on helping the user on-boarding and quality-of-life features that would help people review more code, faster, with less effort.

For start, I’ve just finished preparing the cargo-crev - Getting Started Guide. It will ultimately be generated as a part of rustdoc for cargo-crev, and available on docs.rs, but until then it can be viewed as a markdown document on github. It might also come handy as an example for people that want to add User Guides to their projects.

Since I’m not a native speaker, and not a best writer/editor, and can only dedicate so much time into preparing it, I will greatly appreciate any feedback, to iron it out before it lands immutably on docs.rs as a part of 0.8 release.

From the feature side - the master branch contains “differential reviews” feature now. It is still early, and it will be enhanced, but cargo crev diff allows reviewing diffs between crate versions, and cargo crev review --diff allow signing differential review proofs.

Many people that tried out crev were worried about amount of work necessary to keep up with the constantly evolving ecosystem, and this feature is meant to address precisely that.

A differential review proof contains a new package-diff-base section:

-----BEGIN CREV PACKAGE REVIEW-----
version: -1
date: "2019-06-18T21:58:41.597889623-07:00"
from:
  id-type: crev
  id: FYlr8YoYGVvDwHQxqEIs89reKKDy-oWisoO0qXXEfHE
  url: "https://github.com/dpc/crev-proofs"
package:
  source: "https://crates.io"
  name: byteorder
  version: 1.3.1
  revision: 64c03fb383289f8e42b2892bf72297879777a238
  digest: Zh-2Tbe325ObJ51-O46m-B4hT_WUMnK2GSJJXVNKpXg
package-diff-base:
  source: "https://crates.io"
  name: byteorder
  version: 1.2.7
  revision: bdcc6bf676a1ed17eae68257bfa4726a1f0ec068
  digest: tm4tSfypGXF8-ESvMqH9Pw76GxIDm1UPVFHWF6LUZq8
review:
  thoroughness: low
  understanding: medium
  rating: strong
comment: "Good test coverage, good documentation. LGTM"
-----BEGIN CREV PACKAGE REVIEW SIGNATURE-----
BptAv_o_uuCUqELUezCkY5vdrGJlT5E1Yfh8cVMCM7-0vKZsdTyz3X3E7whxTDNvkqx-P1J6rb2S9VmLMLB-DA
-----END CREV PACKAGE REVIEW-----

indicating which base version the reviewer considered as trustworthy, when reviewing diff to the version from the main package section. Couple of other things changed to make differential reviews a practical way to keep up with new releases.

As always - all feedback is greatly appreciated.

I’m still hoping that the idea will gain enough traction. In the near future I am hopping to announce a first reputable and commercial user using cargo-crev at least internally, and hopefully externally as well. Everything is still in research phase, so fingers-crossed. Stay tuned!

12 Likes

This is very interesting. While the tool is essential it looks like nothing can be done without a big (and somewhat trusted) community. Is there more on that than just the gitter channel ?

A big community would be a big plus, but I don’t think it’s required. At very least cargo crev is useful to identify crates that have: a lot of unsafe, not a lot of other users, unknown authors and no known reviews. After that it useful to keep track of what stuff was already reviewed.

I still believe that the core of crev ecosystem will be companies using Rust.My next guide should be "cargo-crev for organizations".