Rust libz blitz!

[brson]

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?

[KodrAus]

I think it’s a pretty intimidating process but it’s actually really simple to e.g. go over the toml crate and make a list of documentation remediations.

Edit: I made a desperate plea to twir.

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.

[brson]

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

• @msehnout used ? in docs
• @jcsoo added an example for content_first
• @yufengwng added links in DirEntry docs
• @yufengwng added links to IntoIter and FilterEntry docs
• @alisha17 added links to WalkDir docs
• @AndyGauge began better documenting some iterator methods
• @budziq added the html_root_url attribute
• @tmccombs begin implementing Derive
• @tmccombs added CI badges
• @budziq added categories to Cargo.toml
• @jeremielate renamed Iter to IntoIter
• @jeremielate renamed IterFilterEntry to FilterEntry
• @nivkner removed WalkDirIterator
• @shssoichiro began documenting why unwraps won’t fail
• @jeremielate began removing is_same_file

log

• @ohm1280 began adding builders for Metadata, Record, and Level
• @jesusbv began adding log levels to crate docs
• @alisha17 converted set_logger to panic on error

url

• @hngnaig added examples to Url methods

API guidelines

• @behnam made small fixes to the API guidelines

cookbook

• @budziq bumped skeptic to 0.10
• @jonashagstedt fixed a typo
• @alisha17 updated a walkdir example to use follow_links

[sebasmagri]

Hi!

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

Please find it’s evaluation thread here.

[briansmith]

@budziq is looking for cookbook ideas for […] ring […]

I’m not sure if I understand the cookbook idea. We already have some cookbook-ish examples in the ring documentation, e.g. https://briansmith.org/rustdoc/ring/pbkdf2/index.html#password-database-example and https://briansmith.org/rustdoc/ring/signature/index.html#examples 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.

[ericho]

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

However i was unable to set it as a wiki.

[ericho]

I added num_cpus to the crate list.

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

[budziq]

I’m not sure if I understand the cookbook idea.

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 . 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.

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

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

[briansmith]

@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.

[brson]

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

However i was unable to set it as a wiki.

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

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

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

[brson]

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.

[brson]

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.

[brson]

@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.

[briansmith]

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.

[brson]

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.

[brson]

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

[brson]

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

[brson]

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.

[brson]

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!

• rand
• threadpool
• env_logger
• same-file

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

• @opilar implemented Clone, Default and Debug for Config
• @opilar implemented Clone and Debug for Tool
• @opilar added examples for include, define, and flags
• @opilar added examples for shared_flag and static_flag

log

• @ohm1280 continued work on builders for Metadat, Record, and Log
• @jesusbv documented basic usage

url

• @rap2hpoutre added error documentation to the parse function

walkdir

• @alisha17 began correcting errors in WalkDir types
• @expenses began linking references in docs

cookbook

• @budziq filed a bunch of new example issues
• @portal-chan added glob examples
• @budziq fixed some tests that were failing on windows
• @sb89 added an example of logging to stdout instead of stderr

guidelines

• @benham replaced some outdated syntax

other

• @theduke is bumping heapsize’s version so url can upgrade it

[budziq]

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

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!