Cogito, Ergo Sumana

Categories: sumana | Open Source and Free Culture:Advice:Maintainership book

Book project on open source maintainer skills, starting in 2020

: Breaking Release Bottlenecks -- What Changeset Can Do: I did some volunteer work earlier this year, helping rejuvenate pipenv (a command-line tool that some people use to help handle Python packages they make and use). Here's what I did, how long it took, and how you can do the same.

Pipenv's maintainers had not released a new version since November 2018, and users were concerned (in many cases switching to competitors). In early March of this year, someone suggested that perhaps the official Python Packaging User Guide should stop recommending it. I saw that suggestion and went into the relevant Internet Relay Chat (IRC) channel to nudge one of pipenv's maintainers and to ask: what do you need? What's blocking you?

Dan Ryan ("techalchemy") knew what was blocking him:

techalchemy: if you're purely evaluating 'how do we release the code', yeah I might just be the main roadblock?
techalchemy: someone to yell at me to stop doing things that are not related to the goal?
techalchemy: lol
sumanah: let us assume that a successful release -- even as a pre-alpha -- is something that does not instantly break every user's life
techalchemy: yeah longer term planning though would require tech writing for sure and onboarding help, god do I struggle with that
techalchemy: have you heard me explain something...
sumanah: if you JUST want someone to yell at you to stop doing those unrelated things, just for about a month, then that can be cheaper .... would you actually _listen_ to that person?
techalchemy: historically speaking, I'd insist I was doing something important briefly but probably reassess, I do know what needs to happen
sumanah: :-) ok. So, how frequently do you need those checkins? like, 4 times a day, 5 days a week?
techalchemy: hopefully not that much, but I could see a few checkins being helpful especially if we were also onboarding some new people
sumanah: techalchemy: ~10 minutes of conversation, via IRC, 4 times a day, 5 days a week, for 3 weeks....

That would have worked out to about ten hours. We underestimated how long it would take Dan to address some nasty continuous integration bugs, so instead of three weeks it took three months. Over those months, I donated about 15 hours of my time, helping him release two betas, then a stable version in May. Given my current hourly rates, this constitutes a donation worth a few thousand dollars, which is infinitesimal compared to the value unlocked by expediting a pipenv release.

Dan needed someone to help him with prioritization, release management, and communications. So I:

Phil Gyford noticed that initial IRC conversation and said:

It's kind of fascinating as an example of bottlenecks in open source development and the importance of project managers.

And Yoz Grahame replied:

I regularly have conversations like this, and it's a toss-up as to which of the two roles I play.

Yeah. An external perspective can help a lot. And, ideally, a project manager is a supportive accountability partner who helps with the bits you're not great at.

If you/your company depends on an open source project and you're getting annoyed or worried because the release cadence has slowed to a standstill, there's a strong chance you can turn that around. If someone on your team can spend a few hours complementing the existing maintainers and helping unblock them, that could save you a bundle compared to forking or switching dependencies. Try talking with the maintainers about what they need. And I do mean talking, as in, synchronous conversation via voice or chat, so you can build some trust and get the kind of conversation you see in the IRC log above.

Or: contact Changeset Consulting for a free initial 30-minute chat. Maybe it'll only cost you a few thousand dollars to get that bottleneck unblocked. Let's find out!

Filed under:

: Remedial Skills In Open-To-The-Public Working Groups:

I'm talking in this post about wikis, political clubs, open source projects, fanvidding exchanges -- any groups where people try to work together and are open to the public.

"No, what's that?"

Some people joining your groups don't know things you take for granted.

Years ago, while helping new applicants to Google Summer of Code get into working on (I think) MediaWiki or Zulip, I was talking with a person who was (at that time) a student in an Indian engineering college. He had run into trouble and was trying to debug a setup issue. He seemed to be asking for help but not systematically investigating what the problem might be.

So I said, let me give you some tips on troubleshooting. You've heard of the scientific method?

He said: no, what's that?

I gave him a link to the Simple English Wikipedia article on it -- and to the They Might Be Giants video for their song "Put It To The Test", on forming falsifiable hypotheses and testing them. I asked him to watch and read them and then tell me when he had done so. He did.

They Might Be Giants - Put It to the Test from They Might Be Giants on Vimeo.

I then said: so, you do that. You come up with a hypothesis for what might be the problem, and figure out how you would check to see if that is the case. You run the experiment, and you use the resulting data to refine your hypothesis -- if you're wrong, you try to come up with a new hypothesis. And then you either find and fix the problem, or if you get stuck, you at least have a bunch of data to give someone so they can help you better.

He said: THIS IS AMAZING! I'M GONNA USE THIS ALL THE TIME! And I was like IT IS! And then in a separate private conversation with colleagues, I was privately very angry with the educational system that had let him get that far without teaching him this!

[This is one of the experiences that led to me writing a fairly well-regarded blog post for new open source software contributors, on the scientific method, learning from and contributing to shared notes and logs, and self-reliance and interdependence.]


Some lessons here for you:

  1. Don't act surprised when people say they don't know something. Because (as I said a few years back) that’s just a dominance display. That's grandstanding. That makes the other person feel a little bit bad and makes them less likely to show you vulnerability in the future. It makes them more likely to go off and surround themselves in a protective shell of seeming knowledge before ever contacting you again.
  2. Some gaps you can remediate. Sometimes it's as quick as the explanation and links I used above. Sometimes it's more involved, as with providing free English tutoring to your internship applicants. Sometimes remediation takes a lot more work, and you may not have time to provide it; see my suggestions in "How to Teach And Include Volunteers who Write Poor Patches" which include some lower-effort options, like the section "Using their knowledge and curiosity to improve the project in other ways."

    In open source projects, I think it's also okay to exclude unskilled people from a project based on "we do not have time to help them learn remedial skills, and this is not a suitable project for novices." If you are going to do this, explicit is better than implicit. You should try to forewarn contributors with explicit "not good for beginners/prerequisite skills are [list]" language in your README and CONTRIBUTORS files. And when you need to tell contributors that they aren't ready to participate in your group yet, you should offer them a redirect to a project more suitable to their skill level, you should take care not to insult them while redirecting, and you should tell them they'll be welcome back in the future after learning more of the prerequisites.

  3. The scientific method is still as kickass a cognitive tool as it has ever been. It's amazing and empowering!

Thanks to Dr Linda McIver for the conversation that spurred this post.

Filed under:

(1) : MOSS Video, BSSw Honorable Mention, and The Maintainership Book I Am Writing:


Mozilla interviewed me about the Python Package Index (PyPI), a USD$170,000 Mozilla Open Source Support award I helped the Python Software Foundation get in 2017, and how we used that money to revamp PyPI and drive it forward in 2017 and 2018.

From that interview, they condensed a video (2 minutes, 14 seconds) featuring, for instance, slo-mo footage of me making air quotes. Their tweet calls me "a driving force behind" PyPI, and given how many people were working on it way before I was, that's quite a compliment!

I will put a transcript in the comments of this blog post.

(Please note that they massively condensed this video from 30+ minutes of interview. In the video, I say, "the site got popular before the code got good". In the interview, I did not just say that without acknowledging the tremendous effort of past volunteers who worked on the previous iteration of PyPI and kept the site going through massive infrastructure challenges, but that's been edited (for brevity, I assume).)

This video is the first in a series meant to encourage people to apply for MOSS funding. I mentioned MOSS in my grants roundup last month. If you want to figure out whether to apply for MOSS funding for your open source software project, and you need help, ping me for a free 20-minute chat or phone call and I can give you some quick advice. (Offer limited in case literally a hundred people contact me, which is unlikely.)


The Better Scientific Software (BSSw) Fellowship Program "gives recognition and funding to leaders and advocates of high-quality scientific software." I'm one of three Honorable Mentions for 2020.

The main goal of the BSSw Fellowship program is to foster and promote practices, processes, and tools to improve developer productivity and software sustainability of scientific code. We also anticipate accumulating a growing community of BSSw Fellowship alums who can serve as leaders, mentors, and consultants to increase the visibility of those involved in scientific software production and sustainability in the pursuit of scientific discovery.

Exascale Computing Project logoThat's why I'll be at the Exascale Computing Project Annual Meeting next week in Houston, so if you're there, I hope to meet you. In particular I'd like to meet the leaders of open source projects who want help streamlining contribution processes, growing more maintainers, managing communications with stakeholders, participating in internship projects like Google Summer of Code and Outreachy, expediting releases, and getting more out of hackathons. My consulting firm provides these services, and at ECPAM I can give you some free advice.


And here's the project I'm working on -- why I received this honor.

In 2020, I am writing the first draft of a book teaching the skills open source software maintainers need, aimed at those working scientists and other contributors who have never managed public-facing projects before.

More than developer time, maintainership -- coordination, leadership, and management -- is a bottleneck in software sustainability. The lack of skilled managers is a huge blocker to the sustainability of Free/Libre Open Source Software (FLOSS) infrastructure.

Many FLOSS project maintainers lack management experience and skill. This textbook/self-help guide for new and current maintainers of existing projects ("brownfield projects") will focus on teaching specific project management skills in the context of FLOSS. This will provide scalable guidance, enabling existing FLOSS contributors to become more effective maintainers.

Existing "how to run a FLOSS project" documentation (such as Karl Fogel's Producing Open Source Software) addresses fresh-start "greenfield" projects rather than more common "brownfield", and doesn't teach specific project management skills (e.g., getting to know a team, creating roadmaps, running asynchronous meetings, managing budgets, and writing email memos). Existing educational pathways for scientists and developers (The Carpentries, internships and code schools) don't cover FLOSS-specific management skills.

So I'm writing a sequel to Karl's book -- with his blessing -- and I'm excited to see how I can more scalably share the lessons I've learned in more than a decade of leading open source projects.

I don't yet have a full outline, a publisher, or a length in mind. I'll be posting more here as I grow my plans. Thanks to BSSw and all my colleagues and friends who have encouraged me.

Filed under:

: What Does A Volunteer Development Coordinator Do?: A giant wall of text follows, giving a snapshot of work I do. I nurture the software community that supports the Wikimedia movement. So here's a big swath of stuff I did between February 1st and today.

Wrote and posted a blog entry about the San Francisco hackathon. Still need to do more followup with participants.

Handed over the MediaWiki 1.19 deployment communications plan to Guillaume Paumier, WMF Technical Communications Manager. He blogged a summary of the deployment and of our efforts and that's just the tip of the iceberg; he also set up a global message delivery and improved the CentralNotice maintenance message and did even more to make sure that we thoroughly communicate about the upcoming deployment to all the Wikimedia communities. I also shared information with various folks regarding testing of site-specific gadgets on 1.19.

I sent at least 285 work-related emails. That's 41 per workday but I definitely sent some work-related email on weekends.

Some patch queue work, responding to contributors and getting experienced developers to review the patches. I'm just trying to keep our queue from growing while code reviewers are mostly focused on getting MediaWiki 1.19 reviewed, polished, and deployed. But I do want to take care of all parts of the volunteer pipeline -- initial outreach and recruiting, training, code improvement, commit access, continued interest and participation, and debriefing when they leave -- so the patch review queue is a continuing worry.

Some work preparing for the Pune hackathon and for GLAMCamp DC, neither of which I am attending. I wrote or edited some tutorials and made a tutorial category which pleases me. We have more good material for workshops and stuff now, yay! And I helped the GLAMCamp people a bit in talking through what technical goals they wanted to achieve during the weekend.

Got dates from Wikimedia Germany for the Berlin hackathon, 1-3 June, and started trumpeting it. Also worked on planning for it and did outreach. For example, I reached out to about 13 chapters that are pursuing or interested in some kind of technology work like, say, funding or working on the offline Wikipedia reader (Wikimedia Switzerland), or usability and accessibility for Wikisource (Wikimedia Italy), or the Toolserver, a shared hosting service for tools and stuff that hackers use to improve or make use of the Wikimedia sites (for example, Wikimedia Germany & Wikimedia Hungary). We hope they can convene, share insights and collaborate at the WMDE hackfest.

Told at least 30 contributors to apply for Wikimania scholarships because the deadline is 16 February.

Talked to some Wikimedia India folks about planning technical events, and contributed to a page of resources for upcoming events.

Worked on some event planning & decisions for a potential event.

Passed the word to some friends, acquaintances, and email lists about some job openings at the Foundation.

Google Summer of Code has been announced, and I am managing MediaWiki's participation. I have started -- flyers, emails, recruiting potential students, improving the wiki page, asking experts whether they might mentor, and so on. I'm trying to start a thing where every major women's college in North America gets a GSoC presentation by March 15th, to improve the number of GSoC applications that come from women; let's see how that goes. MediaWiki still needs to apply to participate as a mentoring organization and acceptances only go out after that, but I'm comfortable spending time preparing anyway. And the women's college outreach will lead to an increase in the number of applications for all the participating open source projects, instead of just aiming a firehose at MediaWiki; that's fine. Like Tim O'Reilly says, aim to create more value than you capture.

Related to that -- I set up a talk for one of our engineers to give at Mills, a women's college that has an interesting interdisciplinary computer science program (both grad and undergrad, the grad program being mixed-sex) and I think it may end up being a really amazing talk. Ian Baker is going to talk about how CS helps us work in Wikimedia engineering, how we collaborate with the community during the design, development, and testing phases, and what skills and experiences come in handy in his job. I'll publicize more once there's an official webpage to point to.

Had a videoconference with a developer and my boss about our conversion to Git. I prepped for it by collecting some questions and getting preliminary answers, and then after the call we ended up with all this raw material and I sent a fairly long summary to the developers' mailing list. There's a lot left to do, and the team needs to work on some open issues, but we have a lot more detail on those TODOs now, so that's good.

Saw a nice email from Erik Möller publicizing the San Francisco hackathon videos and tutorials/documentation, yay!

Talked with a few people about submitting talks to upcoming conferences. I ought to write some preliminary Grace Hopper, Open Source Bridge, and Wikimania proposals this week.

Various volunteer encouragement stuff (pointing to resources, helping with installation or development problems, troubleshooting, teaching, putting confused people in touch with relevant experts, etc.), especially talking in IRC to eager students who want to do GSoC. Many of them are from India. I wonder how many of them see my name and think I'm in India too.

Commit access queue as usual.

Saw privacy policy stuff mentioned on an agenda for an IRC meeting on the 18th, so I talked to a WMF lawyer a little bit about privacy policy stuff for our new Labs infrastructure. We set up a meeting for this week to iron stuff out.

Helped with the monthly report. I have a colleague who wants to learn more about All This Engineering Stuff, so every month we have a call where I explain and teach the context of the report, and for this month's call I suggested we add another colleague who also wants to learn how the tech side works. Who knows, maybe this will turn into a tradition!

Followed up on the GSoC 2011 students who never quite got their projects set up and deployed on Wikimedia servers, and looks like two of them have some time and want to finish it now, yay! Updated the Past Projects page.

Checked in on the UCOSP students who are working on a mobile app for Wiktionary and told them about Wikimania, new mobile research, etc. Also got some feedback from their mentor, Amgine, on how they're doing.

Started an onwiki thread to discuss the MobileFrontend rewrite question(s).

Talked to Oren Bochman, the volunteer who's working on our Lucene search stuff, and followed up on a bunch of his questions/interests.

Ran & attended meetings.

Suggested to the new Wikimedia Kenya chapter that maybe we could collaborate, since they're interested in helping schools get Wikipedia access via offline reading.

Looked into the code review situation by getting a list of committers with their associated numbers of commits, reviews, and statuschanges. It's just a first pass, but it's a start for discovering who's been committing way more than they review, so we can start efforts to mentor them into more code reviewing confidence. I also saw who's been reviewing way more than they commit, and saw a name I wasn't familiar with -- looks like I've now successfully recruited him to come to the Berlin hackathon. :-)

Put two groups of people in touch with each other: did a group-intro mail to people at various institutions working on Wikimedia accessibility, and another to people who want to work on a redesign of's front page.

And there was other miscellaneous stuff, but this is already sooooo TL;DR (too long; didn't read). (Which is funny because that's the name of my team.) Monday awaits!

Filed under:


You can hire me through Changeset Consulting.

Creative Commons License
This work by Sumana Harihareswara is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Permissions beyond the scope of this license may be available by emailing the author at