Rust libz blitz!

libs
102

One of the last blockers on lazy_static is to add CI badges. During the last few reviews though we’ve not been too keen about the imprecision of these badges though, and @dtolnay and I even plan to remove the recommendation from the guidelines. I’m inclined to close this issue. Any opinions?

1 Like
103

I'll put together a quick post on reddit on my experience with libz blitz (which has been very positive) to try encourage people to get involved, because it does look official and daunting.

IMO, running an evaluation doesn't mean having to know everything, and the libs team / crate authors aren't antagonistic actors. Everyone is helpful and wants the process to succeed. I do think there's a degree of mentoring the libs team would need to commit to when someone first picks up an evaluation, but I've already found that to be the case.

104

Status update 2017/07/05

This is another belated status update, covering the time period since 6/23.

The libs team reviewed the error-chain crate at last week’s libs meeting. Unfortunately, due to logistical problems around the Mozilla all-hands, the meeting was not recorded. The meeting notes are on this etherpad though. @aturon or @brson will follow up soon on the thread and file all the bugs.

Some of the big resolutions were:

  • lower the Error trait into probably the alloc crate so no_std error-chain makes sense
  • investigate a complete syntactic redesign to accommodate all the missing capabilities raised in the review. This will certainly require using some form of procedural macros. It may or may not be a 1.0 blocker

Thanks @Yamakaky and @bascule for attending, and thanks to all those who participated in the review.

@KodrAus opened an evalution for same-file, a small support crate that was extracted out of walkdir.

@burntsushi opened an evaluation for gcc. This is the first build-time crate we’ve taken a close look at, so the hope is it has some unique properties. This crate is scheduled for next week, 7/11! Time flies… please go give that thread a look and make any reviews you have soon. I’ll chip in myself before next week.

Very soon we will expect @brson to open the rand evaluation, which is scheduled for 7/25. I’m a bit worried about the time crunch…

@budziq is looking for cookbook ideas for regex, ring, csv, glob, and also same-file. @budziq I will try to help you solidify these into contributor tasks soon but feel free to start making issues of the ones you feel confident about and posting to the twir call for participation.

We are super close to completely closing out the evaluations for bitflags, byteorder, flate2, and lazy_static, and releasing bumped versions.

reqwest is only blocked on associated constants and some decisions about the decomposition of the basic HTTP types. memmap is only blocked on one API refactoring PR that is pending and some followup docs. log has a couple technical changes to make still, particularly structured logging.

We’ve now closed 113 issues against crates in the libz blitz.

walkdir

log

url

API guidelines

cookbook

3 Likes
105

Hi!

I’ve added env_logger to the out of band evaluations.

Please find it’s evaluation thread here.

1 Like
106

I'm not sure if I understand the cookbook idea. We already have some cookbook-ish examples in the ring documentation, e.g. ring::pbkdf2 - Rust and ring::signature - Rust and others. Is this different than what the cookbook is supposed to do? If not, I'd prefer to have the examples for ring in the ring rustdoc so that they can be checked during the running of the ring test suite and changed accordingly as the ring API is improved, instead of being in a separate repo. I imagine that most other crate maintainers would prefer this as well, for the same reasons.

107

Hi, I created the out of band crate evaluation for threadpool.

However i was unable to set it as a wiki.

2 Likes
108

Hi @brson I couldn't find num_cpus in the list, it was removed or is missing?

109

Hi, I'd like to chime in. Cookbook tries to address few problems:

  • crate discoverability - admittedly if readers are already aware about particular examples in crate doc, then our work is done :slight_smile: . But it's likely that new developers will:
    • not know about your excellent crate a all
    • will be confused by a plethora of competing crates and would like to be informed on a community consensus for the "blessed" crate for the job
  • provide a learning curve - starting from trivial ramping up to more complex cases in a uniform coding and writing style (not restricting crate authors to conform to any particular one)
  • provide a problem solution approach to common programming problems. One that is not focused on showing all of the crate bells and whistles but rather the most idiomatic solution for given problem. Each example would be heavily linked to crate and std docs allowing readers to find a more sophisticated solutions.

Currently the cookbook examples are built and tested with skeptic on per commit basis with locked dependencies and nightly via travis cron job with wildcard dependencies to get buildbreak if crate api moves/ evolves. Granted it adds some maintenance burden for the cookbook devs.

I imagine that most other crate maintainers would prefer this as well, for the same reasons.

Well this is a matter of taste really. Some maintainers expressed that they want the added discoverability even if some examples are duplicated but I understand that this may not be always the case and your concerns are perfectly valid.

If I were to judge the ring examples, some of these might be a little beyond the cookbook scope. I would venture that typical cookbook reader might come searching for way to "hash and verify file contents" or "sign and verify a message" and someone searching specifically for "Ed25519 signing" would already get a ring docs as google result. But I might be wrong here, that is why we always solicit crate ideas prior to implementation.

I'm not saying that cookbook solves any of the mentioned problems particularly well (or at all) ATM. It currently suffers from lack of a good story behind it. But this is only a first iteration on its form and design (which will likely change heavily). We would love to hear your thoughts on the cookbook.

Sorry for making this so long :slightly_smiling_face:

3 Likes
110

@ericho Thanks for explaining. I agree in particular that it makes sense to have some kind of progression from simple to more complex things, which is something that we can’t really do in rustdoc since rustdoc has to be written for random-access reading.

Also, reading your description, I realize too that in our documentation for ring, we avoid using any third-party crates and even usually avoid using libstd (because we want to demonstrate that things work for #![no_std] too). It’s pretty problematic to write doc tests that use external code and I think this is a place where the cookbook can demonstrate more interesting things than what a crate’s doctests can reasonably do.

3 Likes
111

Oh, awesome @ericho! I converted it to a wiki.

num_cpus is on this master list. It's not one of the ones I've currently slated for review in the op, but that would be just fine to review as well. I'll add it to the op.

Edit: num_cpus is a @seanmonstar crate. I took the liberty of assuming he will be ok with it going through the ringer and added it to the list. Sorry Sean :slight_smile:

1 Like
112

I updated the op to put the threadpool and env_logger crates under the ‘Other crate evaluations’ sections, removed the empty ‘On-deck’ section, and updated the list of jump-in points at the very top.

This is awesome. All of a sudden we’ve got a bunch of evaluations underway. I posted them to the twir call for participation.

I also opened the rand evaluation. I suspect the 7/25 date for that will slip sadly. It’s too big a subject and two weeks is not enough time.

Thanks everybody for all the help. I will make sure to chip in on all the outstanding evaluations next week, and keep soliciting help working through them.

1 Like
113

I’ve outlined a plan to relicense the cookbook to CC0 here. If you have opinions about this matter you might take a peek. I’d love for somebody to confirm that yes CC0 is the right license for a book of examples.

114

@briansmith raises a good concern about crates being included in the cookbook. It’s important that we get consent from authors before involving them both in crate evaluations and in the cookbook. Some have reasons to not want to participate and we need to respect that. @briansmith if you decide you don’t want ring in the cookbook that is perfectly fine with me. Just let me know.

115

I don’t think it should be required to get consent from a crate author to add things to the cookbook. That would be weird. Also I don’t have any problem with any of my crates having entries in the cookbook. I think @budziq did a good job explaining that it’s not (intended to be) a substitute for examples in the rustdoc of the crate itself.

3 Likes
116

The gcc evaluation is happening tomorrow. There’s been relatively little commentary on this little utility crate, but I think we’ve got some good discussion points and there’s definitely going to a lot of good documentation tasks to fall out of this one.

117

I added the RustFest ticket offer for contributing to the OP.

1 Like
118

OK, I’ve filed the tracking issue for this evaluation:

https://github.com/alexcrichton/gcc-rs/issues/198

There are several here that need some bikeshedding still, or where the details are not clear to me:

https://github.com/alexcrichton/gcc-rs/issues/174

https://github.com/alexcrichton/gcc-rs/issues/184

https://github.com/alexcrichton/gcc-rs/issues/189

https://github.com/alexcrichton/gcc-rs/issues/190

https://github.com/alexcrichton/gcc-rs/issues/191

https://github.com/alexcrichton/gcc-rs/issues/195

This also uncovered one new guidelines issue:

https://github.com/brson/rust-api-guidelines/issues/104

119

I know I still need to file issues for error-chain. Won’t get to that tonight, but at least there’s a bunch of new gcc issues for contributors to take on.

OP is updated. Issues posted to twir.

120

Status update 2017/07/14

Here’s the update for the period spanning from 7/9 to 7/14.

There’s been a blitzsplosion of evaluations opened!

Thanks @KodrAus, @sebasmagri, and @ericho for stepping up and taking those on.

These threads are in need of experienced library authors to check in on them and make sure they are receiving the appropriate attention and consideration - while it’s relatively easy to do the guidelines checklist, some of the best remediations in these evaluations come out of some deeper thinking about the crate, and that requires experience.

We’ll expect these to be open for about two weeks each. Once the guidelines checklists are complete and discussion points raised, I’ll start helping the leads collect them into a set of issues to file. Maybe we can start wrapping some of them up next week to create more contribution opportunities for that RustFest ticket offer.

The gcc evaluation ended and resulting in a bunch of issues to fix. Yay!

mio is scheduled for 8/15, and if we’re going to get that going on schedule it needs a leader to open that evaluation next week.

The rand evaluation is going to the libs team meeting on 7/25, but we’re not going to close it out then. That will just be some expectations-setting, where we make some decisions about the direction we want to take the crate.

gcc

log

url

walkdir

cookbook

guidelines

other

4 Likes
121

@shepmaster has agreed to support all libz blitz crates on https://play.rust-lang.org/ :heart:

This would be an additional incentive for crate authors to join the blitz and good news for the cookbook (we could finally reenable the play button)!

Unfortunately I’ll not be able to followup on this for the next two weeks due to holidays. So if anyone would like to continue [the discussion] (https://github.com/brson/rust-cookbook/issues/87) feel free to chime in!

2 Likes