This post is my personal retrospective of the libz blitz and my part in it. It's also a loose response to the #Rust2018 call for blog posts and a chance to show off my amazingly poor drawing skills. For the part most relevant to #Rust2018, see the last section.
For those who aren't familiar, the libz blitz was an initiative run by Rust's libs team in 2017 to address that year's roadmap goal of raising a solid core of the Rust crate ecosystem to a consistent level of completeness and quality. Specifically it aimed to improve the ecosystem maturity by evaluating and pushing a core set of crates to 1.0 stability. For more details, see the original Rust Libz Blitz blog post. I think one of the great successes of the original blitz planning (which I had nothing to do with) was the creation of a set of community-driven API Guidelines and Cookbook in addition to the crate evaluations themselves.
I want to give a huge thank you to everyone who participated in the libz blitz in 2017. We had an amazingly diverse group of people helping write guidelines, examples, docs, evaluate and contribute. It's been a pleasure working with all of you!
The following is a big raw list of crates we worked with in the libz blitz over 2017. In the last year we the Rust community:
-
produced the API Guidelines
-
evaluated the following set of libraries:
-
produced the Cookbook with examples for:
It's an amazing amount of work when you put it all together and we should all be proud of what we achieved in 2017! In the following sections I'd like to explore some details of the libz blitz that I think either worked well or could be done better.
I'd like to start positive and look at some things I think worked really well in the libz blitz.
Words I picked up from a co-working space :)
The libz blitz had a few key collaborative, but mostly independent, streams of work that made it all happen. We had:
- The crate evaluations
- The Guidelines
- The Cookbook
The success of one of these streams didn't really depend on the success of the others. They all produced valuable output on their own, but also worked together to make the total greater than the sum of the parts.
The value of the libz blitz isn't just about the output though. Evaluations, the Guidelines and the Cookbook continue to be valuable because of their ongoing activity. The Guidelines aren't just a set of checkboxes. They're an active venue for discussing the art of designing Rust APIs. The Cookbook isn't just a set of examples to peruse. It's a friendly place to learn Rust, or even programming in general, and a stepping stone to contribution in other parts of the Rust ecosystem.
I think the libz blitz presents an on-going opportunity for Rust teams to collect and collate feedback on what effective Rust looks like. The blitz format gives the community a chance to discuss the design decisions of a single library within its domain using the Guidelines. Feedback from that evaluation then gets fed back into the Guidelines for future evaluations. There's an element of discovery in every evaluation. I think the diverse set of domains we've applied the Guidelines to are helping shape them into a really well-rounded, fundamental resource for writing Rust.
Let's look at two different community barriers I think the libz blitz successfully tackled:
- barriers to collaboration
- barriers to contribution
Some languages have more accessible core teams than others. Something I really like about our Rust community is that the teams that work on Rust are within the community rather than outside of it. Initiatives like the libz blitz put the libs team within the community and put the community within the libs team. I think the shared sense of ownership over the Rust project is what keeps it moving forward.
I think everyone remembers their first open source contribution, or the first contribution to their open source project from somebody else. As a self-taught developer I remember feeling daunted by the prospect of opening a pull request and having the world scoff at my naivety. Getting started in the open is hard, even more so with an unfamiliar language.
The contribution issues for evaluated crates and Cookbook examples were really effective at breaking down barriers to getting started with Rust, or open source in general. They offered new contributors a safe environment to learn and contribute to a wide range of projects.
The crate evaluations usually went in one of two directions:
- The crate was basically ready for a stable release. We collected a set of issues that amounted to the polish needed to feel really confident about
1.0. - There was more design space in the crate's domain we wanted to explore. We didn't think the crate was fundamentally ready for stabilisation yet.
Crates on the first path fit the blitz format the best, I think. We evaluated them, collected a set of bite-size contributions and the community worked the library into a stable shape. There were some big decisions made too, like renaming the gcc crate to cc, splitting env_logger out from the nursery, and merging the tempfile and tempdir crate APIs.
Crates on the second path were a bit fuzzier, but I think we did a good job shifting focus back to design. The rand crate has since seen a complete revamp. Following the error-chain evaluation we also saw the emergence of the failure crate to try address some of the fundamental challenges with error management in Rust today.
I think the initial goal of how can we stabilise this crate? played an important role in framing the discussions and made it possible to pair big questions with big answers.
Now I'd like to reflect on some things I think we can do better in the future.
I think the way we treat docs in the blitz needs to be rethought in the future. Most of the crates we evaluated needed help fleshing out the documentation and it's hard to find contributors for crate docs. I think most library authors have some vision of what they want in their docs and communicating that vision for others to grasp requires the same kind of effort as just implementing it. When we could compartmentalise improvements to docs, like add an example for the foo method we had no trouble getting those issues resolved, but we didn't effectively drive effort towards fundamental docs work.
The libz blitz format put a lot of pressure on library maintainers. The sudden flood of issues and pull requests from many new contributors can require a lot of shepherding. Some maintainers have a seemingly infinite supply of availability and are happy to chip away at an equally infinite backlog. Some maintainers are focussed on other things and don't have the bandwidth to spare. We tried to cater our approach with each library to the needs of the maintainer, but I don't think we always succeeded. Some maintainers felt like the effort required to shepherd pull requests didn't balance the end result. I think the accessibility of libz blitz issues is a feature that's worth the extra effort, but if a maintainer doesn't have the badwidth to take it on then somebody else needs to.
This is a personal failure. The libz blitz was a community effort, and it depended on community engagement to keep moving. Keeping the community engaged means minimising the friction to getting involved and giving people room to expand their involvement if they want. That's how I ended up involved with the blitz in the first place. I found it challenging to keep things moving, and lost the big picture later in the impl period as the number of open evaluations grew.
I also think I underutilised the resources available to help people get started with the blitz, especially the Find Work site. I didn't want to create noise on reddit by making regular calls for input, but like the dungeon crawler saving their best gear just in case there's a bigger monster around the corner I never made the most of the tools available.
I think steering a community project is an exercise in servant leadership. The Rust community has some true masters of servitude to draw inspiration from and I have a lot to learn :) To wrap it up, my personal list of key takeaways on engaging a community from my libz blitz experience are:
- Be prepared for crickets
- What do you deliver if engagement is low?
- Empower your community
- If you see someone being awesome, let them be awesomer
- Be empathetic
- Remember you're dealing with real people
- Who are motivated by different things
I hope I'll have the chance to do better by the Rust community in the future!
With an idea of what I think worked well and what I think could be done better in 2017, I'd like to explore some ideas to keep the original goal of the libz blitz alive in 2018. That is to say, I think raising a solid core of the Rust crate ecosystem to a consistent level of completeness and quality is still relevant for Rust in 2018.
I think it really comes down to building on the precedent set by the libz blitz over 2018. That doesn't necessarily mean running the same blitz again though. The following are some ideas of how we might continue to support the maturity of the Rust ecosystem.
The Guidelines are a great general resource for writing Rust APIs. The libs team has previously talked about producing companion resources with domain-specific content, like a Networking Guidelines, or maybe a general App Guidelines. I'd like to see the Guidelines we have continue to evolve, discussion continue to happen, and new resources pop up over the next year.
We should continue to expand the Cookbook and make sure the examples remain idiomatic as those idioms evolve. I'd also be interested in having some fuller examples for bigger app-focussed topics. Maintaining those would be more involved though, so I think the model would need to be slightly different to the Cookbook today.
There are still lots of fundamental crates that need help identifying a path to stabilisation that we could focus on in 2018. I don't have as clear a picture of what shape this should take as the other points though. I would like to see the libraries we evaluated in 2017 to continue stabilising, along with new libraries, in some form.
I previously talked about the difficulty with helping improve crate docs. I wonder if there's an opportunity to run a purely docs-focussed blitz. The libz blitz format was great for identifying API issues and collecting them into small units of work but that approach hasn't worked as well for docs. Issues like add an example to method foo can be picked off, but issues like the crate root docs need more detail are much harder to solidify. I'd like to explore the idea of a docz blitz that's designed around those fuzzier requirements.
Looking further into the future, how could the libz blitz tie into epochs? The blitz offers a feedback loop for the Rust teams to engage with the wider community in a structured discussion to identify and collate features of idiomatic APIs. I think this feedback loop will be important to the epoch story, to help solidify the idioms of an upcoming epoch. I think we should run a blitz of some form within each epoch to keep our resources current.
I think I've said enough, but maybe you haven't yet! The #Rust2018 call for blog posts is still ready for your input on what's important to you this year.