Oh yes of course! I liked @brson’s comment. I think having the examples in both places is probably quite valuable!
Thanks! I’ll try to revitalize rust-cookbook in upcoming days. Sorry I didn’t catch the like.
@budziq Yeah, I’ll follow up on this. We’re going to need to put some effort into it to get people to relicense.
I’ve signed myself up to lead the rand evaluation and will open it … Friday I think.
I also added toml to the desired out-of-band evaluations after an unsatisfying experience trying to lead somebody through the docs over the weekend. I intend to solicit more help leading these evaluations to the twir call for participation, but am still agonizing over the difficulty of motivating crate leads (thanks so much @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.
I’m triaging now to create a status report.
Edit: I made a desperate plea to twir.
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?
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.
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
@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.
@jcsoo added an example for
- @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
- @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
- @hngnaig added examples to Url methods
env_logger to the out of band evaluations.
Please find it’s evaluation thread here.
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.
Hi, I created the out of band crate evaluation for
However i was unable to set it as a wiki.
Hi @brson I couldn’t find
num_cpus in the list, it was removed or is missing?
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.
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
@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.
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
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.
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.
@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.
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.
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.
I added the RustFest ticket offer for contributing to the OP.
OK, I’ve filed the tracking issue for this evaluation:
There are several here that need some bikeshedding still, or where the details are not clear to me:
This also uncovered one new guidelines issue: