Getting Unstuck

A Sampler of Advice for Open Source Projects by Sumana Harihareswara

© 2020 Sumana Harihareswara under the Creative Commons Attribution-ShareAlike 4.0 license (CC BY-SA)

Please feel free to share this book, translate it, and reuse it per the license.1

Sumana Harihareswara Changeset Consulting LLC P.O. Box 721160 Jackson Heights, NY 11372 https://changeset.nyc/

+1 (929) 255-4578

Written in emacs and in New York City, 2020. Cover design and layout by Julia Rios Cover photograph by Susanne Stöckli

For Leonard, my foundation. And for Aaron Swartz, our lighthouse.

Table of Contents

• Introduction

• Conducting a SWOT analysis

• How to start thinking about budgets and money

• Teaching and including unskilled volunteers

• An outline of the full book

• Acknowledgments

• About the author

• Feedback welcome

Introduction

Getting Open Source Projects Unstuck

(or, in other words: maintaining legacy open source projects. Below is the introduction for the full, forthcoming book.)

Who this book is for and what you should get out of it

You are about to get an open source project unstuck. Maybe a bunch of work is piling up in the repository and users are getting worried, waiting for a release. Maybe developers have gotten bogged down, trying to finish a big rewrite while maintaining the stable release. Maybe the project's suffering for lack of infrastructure — testing, money, an institutional home. You noticed the problem. So that means it's up to you to fix it. Or you're getting paid to fix it, even though you didn't start this thing. A while ago I blurted out the phrase "dammit-driven leadership." Because sometimes you look around, and you realize something needs doing, and you're the only one who really gets why, so you say, “Dammit, okay, I'll do it, then.” After reading this book, you should be prepared to:

1. Assess a legacy project to decide whether you should get involved. 2. Settle into a legacy project and become a competent and credible contributor. 3. Take charge of a legacy project on a project, people, and financial level. 4. Execute transformative change in a legacy project. 5. Make a legacy project more sustainable, and pass leadership on to someone else.

The tech industry glorifies the founders who build “greenfield” projects, meaning they “started from scratch.” But, in my opinion, most of the genuinely valuable work that needs doing is in the “brownfield” — in codebases that already exist. That's particularly true in free and open source software, where, for 30+ years, we've built and publicly shared valuable tools, together. It's a damn shame if those tools go to waste because no one steps up to take care of deferred maintenance. So let's step up.

Who this book is NOT for

• You've never worked in open source software or contributed to it before.

Go read VM Brasseur's book, Forge Your Future with Open Source.

• You are starting an entirely new open source project.

Go read my advice on starting a new open source project, and then read Karl Fogel's book, Producing Open Source Software. After that, some parts of this book will be useful — sections on meetings, collaboration platforms, money, people management, and so on will be helpful, but you need to read Karl's book first.

• You work for an organization that employs all, or nearly all, of the contributors to the open source project.

Your system dynamics will be different; you can employ career/job incentives such as hiring, promotion, and termination. You have a budget provided by the org, and the boundaries of the company create a default level of trust and collegiality among contributors. This book gives advice for open source projects where project leaders can’t count on that leverage.

Basic assumptions about open source and the tech industries

• There is no one tech industry and there is no one open source community.

A fruit packing company with an IT department, a UK national government agency's developer team, and a Silicon Valley machine learning startup have different attitudes towards open source investment. A 30-year-old systems programming tool with millions of users has different opportunities and needs compared to a six-year-old library gluing a content management system to a social media platform.

• The free software movement and the open source industry are different but intertwined.

I often refer to both, combined, as FLOSS (Free/Libre Open Source Software). You do not have to be an ideological free software believer to be a good leader, but you do need to know enough about the free software perspective to avoid accidentally annoying or enraging colleagues, and to protect your project from getting locked into unequal arrangements with commercial users.

• Open source contributors, as a population, disproportionately want to code.

We have an easy time finding (or being found by) people who want to write features and fix bugs, and integrating these people into our projects. We have a harder time attracting managers, marketers, testers, systems administrators, writers, user experience researchers and designers, customer service experts, event planners, and grant proposal writers, and working well with them and retaining them. Most people who become open source project maintainers did not start out wanting to do maintenance work. They usually wanted to make a cool thing, solve their own needs, or fill a gap that was bothering their peers. They generally had no training, and often have no inclination, regarding long-term product strategy, customer and upstream relationship- building, budgeting and seeking funding, user experience work, and many other necessary disciplines in software leadership. And that’s not a problem, as long as folks with complementary skills can join in and co-lead these projects with them.

• Every open source project has a life cycle.

Sometimes the best choice for a project is to end it. Many open source projects end through quiet attrition, the founders acknowledging reality years after it ought to be evident (if they ever make a public statement). Far better, for contributors and users, is a planned and announced end-of-life. Giving users a heads-up is respectful and frees them to figure out a new path (including a fork under new management), and choosing to actively end a project frees contributors to move on to projects that can engage with their work and deliver it to users.

This is a sampler

This book is a first release — a sampler. I'm releasing this sampler, containing three chapters of the book to come plus an outline of the full book, to:

• Help gauge the market for the full book. • Share some of what I've learned early. • Get feedback from you — email [email protected] with "Unstuck" in the subject line to tell me what you thought.

Conducting a SWOT analysis

Problem

Read this if your team's running into problems like:

Your team has trouble making decisions about what features to implement, what you can deprecate, what platforms/environments to support, how fast the release cadence should be, and related strategic or architectural questions beyond line-level code review and bug- fixing. Your team consistently misses opportunities (such as better tooling/platforms, conference talk slots, grants, or free equipment/travel) because you didn't know they were available, or heard about them too late. Your team gets nastily surprised by new problems over and over, such as a platform vendor ending service, or a competing project adding a killer feature that you don't have. Your team's progress feels frustratingly slow, but no one can pin down why.

Reason for the problem

The project team doesn't have a shared and current understanding of:

• What the project is good for/at, and wants to be/do — fundamentally, why it should exist and keep serving a particular niche, instead of letting competitors serve its users. • Whom you are trying to serve. • What the project is specifically NOT aiming to do/be. • Whom you are specifically NOT trying to serve. • What gets in the way of their users being effective.

Those bits of information will help them understand your tool’s positioning (what is it that your tool uniquely does?) and make product differentiation decisions (why should users use it instead of other tools?).

The team also doesn't know:

• What parts of the current architecture are blocking progress and how urgent it is that they be replaced. • What is happening in the world beyond the project that they'll want to watch out for, to use/leverage or avoid/mitigate.

So it's harder for you to prioritize, and to take charge of your own destiny instead of always being reactive.

Skills you need to solve the problem

I suggest that you do a SWOT analysis, which means taking inventory of your project's

• Strengths • Weaknesses • Opportunities • Threats

I'll briefly introduce the idea here. You can look around online and find a zillion courses, posts, etc. on how to do a proper or speedy SWOT analysis. So I'll refrain from making yet another redundant one here — I'll focus on how to do one in the context of open source.

Note on logistics: In most cases in open source, you should start your work in public and share your work in progress as you go. But this is one of the times that I suggest you do quite a lot of the work in private and make room for some privately-shared sections that would go alongside the public findings. In particular, the "weaknesses" section will probably involve some delicate thoughts on teammates. You don't have to spend weeks on this, writing the definitive assessment of your project. You're not making a geological survey; you're trying to sketch the terrain so you don't miss big mountains and chasms. If you're new to the project, try limiting yourself to 5-8 hours to research this; if you've been contributing for six months or more, try spending 30 minutes to 3 hours.

Why do this, and why this tool?

The point of this is to help you look at a big and scary topic systematically but without getting overwhelmed. Having a few categories to guide your research helps you stay focused on what you're looking for. You can think of these four categories as two pairs:

Internal to the project: strengths and weaknesses External: opportunities and threats

Strategy exercises help you inventory your team and your environment — create a bit of an anatomy diagram and a map. And, yes, these tools are things that you would see on the cover of the Harvard Business Review or of terrible-looking magazines at the airport. In a way, I figure these are kind of like party games. As I see it, we don’t play Apples to Apples because we want to play Apples to Apples in particular. The specific game is less important than the opportunity it creates to do an activity together. The point is for people to explore some ideas with others (and to make up for the lack of other opportunities to talk at length and in depth). Or: think of it like writing a spec. The point is to get people together and get them thinking about the big picture. SWOT exists alongside other mapping exercises to help you discover strategic opportunities and risks, so I’ll explain why I’ve chosen SWOT. You could try out “PEST”, which assesses political, economic, sociological, and technological factors. Or you could assess the “5 Forces”: the threat of new entrants, customer bargaining power, and threat of substitutes, all affecting the competitors in an industry jockeying for position. But every lens is better at showing some things and worse at showing others. PEST and 5 Forces can be harder to apply to projects where you and the rest of the team are totally fine with a zero-finances project; everyone is a volunteer, and the team wants the project to stay that way. And they’re not that applicable when the relationships among you, your upstreams, your downstreams, your users, and your "competitors" is more collaborative than adversarial. So, I've chosen to suggest SWOT because I think it's a fairly good match for the vast majority of open source projects.

Example

Here's an example SWOT for pip, the main Python package installation tool.

Strengths:

• Fresh and thorough tests for many parts of the codebase. • Ships with recent versions of Python — wide availability and name recognition, and built-in distribution pathway. • Clear and established deprecation pathway, and new flags to help consistently roll out new beta features and make deprecated features temporarily available. • Fresh user experience work has improved error and informational output and provided maintainers with feature design and user research training and templates.

Weaknesses:

• No one is paid to work on pip full-time, or even part-time, consistently. • Parts of the code base are hard to understand and the architecture is poorly documented, making it harder for new contributors to help. • Inherent complexity of Python packaging as a domain slows down or hampers: o User experience and technical writing work — contributors take a very long time to onboard. o Architectural and interoperability change, as when new features need to wait for a PEP or for implementation in PyPI. • Pull request and issue backlog makes it harder to keep helpful users and contributors engaged. • Few triagers and similar helpers relative to support load.

Opportunities:

• Distributed computing offers possibilities for testing across pip's deep and wide support matrix. • After January 2021, dropping Python 2 support will free development resources to concentrate on Python 3 support. • Since Python is so key to scientific computing, institutional funders are likely to be interested in funding pip work.

Threats:

• Many users prefer, or are moving towards, alternative tools for installing and managing Python packages (pipenv, poetry, conda/Anaconda, Docker, and others), which increases complexity of environments/interactions pip needs to deal with. In particular: o Anaconda is better funded. o Poetry gets rave reviews for its user experience design. • Hot competition for Python as a language (especially versus Go and Rust) reduces the need for pip. • Possible backlash against new dependency resolver may bog maintainers down in support load.

How to develop this skill

• Pair up with a friend to make and compare assessments.

Decide together which project to assess. Then split up. Each of you should take 60-90 minutes to do some internet research to assess the project's strengths, weaknesses, opportunities, and threats; jot down some bullet points. Then get back together and discuss — what did you find?

• Read retrospectives on the successes and failures of fairly substantive software projects.

I suggest ninja, Movable Type, and JSHint. If you're up for a longer work, Scott Rosenberg's "Dreaming in Code" is a 2008 retrospective of the Chandler project; more recent retrospectives are available. Ask yourself: how would you categorize these projects' SWOTs?

Sumana's personal perspective

This problem (like several I discuss in this book) emerges because most open source projects emerge organically, and because the people in those groups are often disinclined to take time away from coding to do other necessary work. Whenever people team up to work on something, they have to spend some time talking together to decide on what to do and how to do it (what I call "alignment work") and some time apart carrying out those decisions (what I call "execution work"). Open source projects — especially all-volunteer ones — underinvest in alignment work, and an occasional assessment like a SWOT analysis helps gauge and make up for that.

Key takeaways

• Sketching out the project's strengths, weaknesses, opportunities, and strengths will help you figure out what your project is and isn't, and help you prioritize. • You can make this assessment yourself, and it should take hours, not weeks.

Related chapters you might like

If you find this chapter useful, you might like chapters in the full book such as:

"Initial project audit":

You need to be able to make a determination of one of the four following categories:

• This project is humming along fine and does not need my help. • This project is unsalvageable and should be mothballed. • Other people could make the change this project needs, but I am not able to be one of them. • This project's strengths and needs are a good fit for what I can offer!

You will do this through a combination of asynchronous assessment and informal conversation with whoever brought you in.

"Informal conversations with the people who brought you in":

Questions to ask include:

• Who is important? • Who started the project? Are they still around? • Whose voices hold sway in developer and maintainer discussions? And: are there people whom others don't want to annoy? • Who holds the keys to the kingdom?

Who has commit rights to the source control repository, and who has publication rights on any release platforms (such as CPAN, Maven Central, RubyGems, or PyPI)? Furthermore, who controls bug triage/closing rights, the domain name registration, the Twitter/Mastodon/Facebook accounts, continuous integration administration, website and Read the Docs admin rights, and the email accounts?

• Who represents the hearts and minds of the users?

Whose concerns are important to listen to, because they're often right on engineering and/or on what a lot of users care about?

• Why does this project exist, and should it still? • Why did the founders start it?

Are there any old documents/platforms from that time?

• Has it achieved its goals? • How much of the burden/work to be done is now legacy maintenance versus making new stuff?

How to start thinking about budgets and money

What money can do

Problem

Read this if your project is stagnating and feels like there’s no possible way it could move forward. This might be because everyone's a volunteer and all their time is spoken for, and/or all the people who know stuff about the project are full-time busy.

Reason for the problem

Work is done by people. People do work because they enjoy it or because they want to encourage or prevent some outcome. A lot of the time, a grassroots open source project2 starts as a straightforward idea. The only people who depend on it are the people who work on it. There's an organic relationship between the workers and the work; people work on it because they want to make the thing exist or because they like the challenges involved. They are founders. But then complexity grows. The complexity often isn't in the core idea, but in executing it so that it meets what people need of it. What platforms does it run on? Is it accessible to disabled people? What versions of programming languages and frameworks does it work with? What data formats can it interoperate with? Internationalization and API? The more complex the project, the more mental effort it takes to work on it and the more skill and domain knowledge it takes to fix and improve things. And barriers to new contributors creep up; is there an easy way to spin up a developer onboarding environment? Can new folks get a good grasp of the core idea of the software, what's on the roadmap, and the likely dev cadence of the project from public docs/etc., or do they have to guess? And, as a project grows more mature, it often runs into new software engineering challenges. Some of them are architectural; developers may realize they need a ground-up rewrite or a massive refactoring. But how can the developers make these changes safely? Is there automated testing/CI? How good is the test suite? Users depend on the existing behavior and interfaces; is there a deprecation policy, and some way to systematically tell users about upcoming changes? Plus of course there's the user support load, which rises keeping pace with usage, not with number of team members. All of this is often far afield from the core idea and "we want this thing to exist" desire that originally drove the founders. They often wanted to be — and were prepared to be, trained to be, capable of being — founders, architects, lead developers, but not maintainers. And their careers and personal lives have been ticking along, not staying still, as the project matured. Perhaps the FLOSS project has even helped them achieve some job security. Spare time is scarcer — and the increased complexity and greater customer support load of the project means that the backlogged work includes loading project state into their heads, answering annoyed people, etc. which is more arduous to fit into spare moments. Their volunteer spirit flags. And there are no other co-maintainers sitting on the bench fresh and ready; those interested are already participating and overwhelmed, and those knowledgeable enough but currently uninvolved are almost certainly unwilling to come volunteer again, and have implicitly chosen to leave the project (even if they have not done so explicitly). The despair that comes with this situation should not be underestimated.

Skills you need to solve the problem

• Recognize that any despair you are feeling is temporary and not an accurate assessment.

Your situation has resolutions available. Note that I didn't say "solutions"; some resolutions may include major team members leaving, the project dissolving, or other unpleasant endings. But you are not trapped in stasis.

• Use the project audit, inventory, and strategic mapping you've done earlier to help you think through possible outcomes for this project.

When I am assessing, for example, Autoconf, what I personally want is for the "is Autoconf a going concern?" question to be resolved. I am genuinely fine with it being resolved as "yes, and here are the commitments of time and money that will keep it chugging along" OR as "no, and everyone should assume it is end-of-lifed". Right now I think there's a stronger chance of the former. But if we can't get actual commitments for the minimum it takes to keep the project healthy, I would be inclined to say, "hey, users, you should basically consider Autoconf to be end-of-lifed, in that you should not count on any further releases ever happening. If you are fine with sticking with the last existing release, cool. Otherwise, start migrating to other tools."

• Learn some very basic accounting so it's easier for you to look at other organizations' budgets and financial statements.

Accounting is a way to inventory where you are and what resources you have. I figure that accounting — being able to read the basic documents, like a balance sheet, income statement, profit and loss — is like being able to read the real basics of your own medical chart. For an organization that you care about, money is like its blood. So if you care about it, and you want to know how it's doing, being able to understand the real basics of that is about as important as knowing the basic health history and status of you and people you care about. And, as you start thinking about budgets, you'll find it useful to look at financial and tax documents from your possible funders — grant-giving foundations, companies that use your software, etc. — and from your peers. For more guidance, check out the book How to Read A Financial Report by John A. Tracy, which explains a few really key ratios to look for in the relevant numbers that would be publicly available.

Examples

PyPI overhaul

I started thinking about project budgets for the Python Package Index (pypi.org) after a friend suggested that the long-awaited PyPI overhaul could use a project manager. Volunteers decided that we wanted to apply for Mozilla Open Source Support funding. We triaged bugs, figured out what work needed to happen in order to promote the new site to production and decommission the old one, and made some rough assessments of how much time it would take to do those things. The four people interested in working on it for money (as contractors) decided on what hourly rates we were interested in taking, and the Packaging Working Group of the PSF multiplied out the hourly rates times the amount of (estimated) work needed in order to figure out a rough budget. We made a proposal, had some back-and-forth with Mozilla, and successfully got USD$170,000.

The Fundable Projects list

After helping important Python packaging projects get some funding for important work, I thought, There must be a bunch more that we could do if we got funding. In early 2019, I started a wiki page to list specific ideas that meet these fairly broad criteria:

1. The Python packaging community wants them 2. They are fairly well-scoped 3. They would happen much faster if the Packaging Working Group got funding to achieve them

The list started with a single item. Now it's a GitHub repository and the criteria have a little more detail. We check whether the following is true for each proposal

1. The Python packaging community wants it: there's already consensus among project maintainers, and if a PEP (Python Enhancement Proposal) is involved, it's been accepted. 2. Fairly well-scoped 3. Fundable: would happen much faster if the Packaging Working Group got funding to implement the work. (So, it has to be legal and physically possible.)

How to develop this skill

Here are a couple of exercises.

A. What Can You Do For $5,000?

At the time of this writing, here are some ranges for hourly rates, assuming you want to hire a not-entry-level contributor on an hourly basis in the United States:

• Software developer: USD$80-$250/hour (for intermediate-skilled maybe $150) • User experience expert: USD$110-$250/hour • Technical writer: USD $80-180/hour • Project manager: USD $75-230/hour (in my experience, a project manager can often also do some amount of tech writing and testing)

Assume that you have a project that needs some software development work, some project management work, and a little bit of technical writing. Assume that you have $5,000 in funding and that each of your individual workers comes in right around the middle of the price range for that profession. What are three different ways you can split $5,000 among the three categories of work?

B. How Much Does It Cost to Make a “One-Week" Change?

When a developer says that something will take a week of work, sometimes what they mean is that the fundamental work of writing the code will take about a week (35-40 hours of work over 5 days). This often omits:

• Testing, getting tests to pass, and fixing newly revealed bugs. • Waiting for other people to review the code, revising in response to those comments, and going through one or more further cycles. • Communicating about the change in developer and user documentation, and email to the users' mailing list.

Use your past experience to think about how much time those might take. How many days or hours will it probably take to implement a "one-week" change? Based on the hourly rates mentioned above, how much will that cost?

Sumana's personal perspective

Let's look at these archetypes of open source projects. Some projects start as a well-resourced thing, housed at a big, for-profit company. We don't need to worry about those here. Some are wee hobby projects that no one depends on, or, the people who depend on them are basically the same set that maintains them. But in between those two extremes we have the land of asymmetry of usage and investment. And that's where money can do a lot, and where there's a lot of opportunity to level up projects with relatively small (under $250,000) cash infusions.

References

In writing this chapter I drew on:

• "Apply for Grants to Fund Open Source Work", a talk I virtually gave at PyOhio in July 2020. • "Learn Tech Management in 45 Minutes", a talk I gave at Open Source Bridge in 2011

I also recommend you read:

• These blog posts on unfairness and burnout in free and open source software. • Making Software: What Really Works, and Why We Believe It, in particular its chapters on new contributors, their need to understand the project's design rationale, and what they need in documentation.

Related chapters you might like

If you find this chapter useful, you might like chapters in the full book such as:

• "How to start thinking about funding proposals (such as grant proposals)”

When is it worth applying? Different projects need different amounts of money. A one-time gift of $10K (about 60-100 hours of work at USD$100-150/hour) is not enough to make a significant dent in some of the listed fundable packaging tasks, but $10K could support a "get the next release out and clean up docs/bugtracker/patch queue" effort for your favorite library. It might take 10-20 hours to research and draft a multi-page grant proposal from scratch (it gets easier when you can copy and paste from previous proposals or planning documents for the same software project). Sometimes it takes longer if a bunch of stakeholders (such as project maintainers) have to agree on priorities and scope.

• "Find your successors"

In informal groups, we usually don't think about endings, and in FLOSS there is a taboo against thinking explicitly about ambition, leadership, and succession. Also: many thoughtful, productive people are already busy with personal commitments and will feel external pressures to say no to further responsibilities. You need multiple candidates; you need a strong bench.

Teaching and Including Unskilled Volunteers

Problem

Read this if some contributors to your project — through poor contributions and related interactions — are unhelpful or even a net loss for the project. One way this can show up is when some of the volunteers who join you are less-skilled programmers, and they're submitting pull requests/patches that need a lot of review and reworking before you can merge them.

Reason for the problem

You have two opposing values: you want to get things done, and you want to be open to the public. Some people joining your groups don't know things you take for granted. Or they're just not as skilled as most of the people working on the project. This means that your project has successfully signaled that you're open to new contributors, including people who aren't professional software engineers.

Skills you need to solve the problem

You need to learn to teach and include volunteers who write poor patches or otherwise don't know important prerequisites. This includes helping less-skilled programmers improve their code, dealing with the poor-quality pull requests themselves, and redirecting their energies to improve your project in other ways.

In sequence, you will need to:

• Assess a new contributor's skill level. • Including enthusiasm. • Check/update your previous assessment (from the project audit) of what the project's capacity is for this kind of newbie. • Cadence of feedback, especially kind of exhausting feedback. • Sheer time. • Where are you in the release cycle? • Remediate what you can. • Nicely show the door to contributors who are a poor fit in ways you can't remediate. • Put new guidance into place to help future candidates align expectations with reality. • Ensure you have a easy developer setup process and great test coverage so it's easy for new people to get up and running fast.

General principles

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. Some gaps you can remediate. Sometimes it's as quick as the explanation and links I share in the example later in this chapter. 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 tips below, 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 if you do not have time to help them learn remedial skills, and if yours is inherently not a suitable project for novices because working on it requires so much domain-specific knowledge. 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.

Specific tactics

How do you improve these volunteers' work, help them do productive things for the project, and encourage and include them? My suggestions for you fall into three categories: helping them improve their code, dealing with the poor-quality pull requests themselves, and redirecting their energies to improve the project in other ways.

Teaching them to improve their code

• Collect and suggest relevant learning resources, like certain talk recordings or freely available articles/exercises (e.g., The Architecture of Open Source Applications), and ask them to come back after they've watched/read/done them. Example: Zulip’s collection.

• If developers have trouble writing good comments and commit messages, or diving into the codebase to find relevant files and commits, point them to my blog post "On the scientific method and usable history". It explains why it's important to do that, and gives them pointers.

• Ask more experienced contributors to pair program with them, both as leader and as follower. Here are a few tools to help.

• Run live coding exercises, over chat or video, where an experienced developer speaks aloud as she writes a bugfix, including all the little steps like searching for related commits, setting up and running tests, etc. This enables newer developers to learn a lot of tips that help them work faster and write higher-quality code. I’ve done this at Wikimedia with live video and we use Zulip for a live text approach (see Alicja Raszkowska's transcript and notes of one such session).

• If a big problem with their submissions is poor English writing skills, run some English tutoring sessions.

Dealing with poor patches themselves

• Write a code review guide (example from Zulip) and point to it liberally when giving criticism to contributors.

• While reviewing pull requests, use GitHub saved replies as much as you can. Point to coding standards, guides to rebasing, etc. Here's one set you can copy and modify.

• Follow Sage Sharp's advice on three-phase review, and consider using nicely phrased labels/tags in your patch tracker to indicate what phase the PR is in. Then you can, while reviewing, search for particular labels and concentrate on a class of patches at once.

• Be kind even as you criticize (see this Zulip example) and prioritize getting back to people fast, to signal that you genuinely want them to come back with a better patch (see this Mozilla analysis).

Using their knowledge and curiosity to improve the project in other ways

• Ask these developers to write “discovery reports". They're already user-testing your developer onboarding process; ask them for their experiences, so you can find and fix pain points.

• Ask them to run through some manual testing (example manual testing guide from Zulip), and to tell you how long certain kinds of tests took, so you can get bug reports and improve the docs.

• Ask them to teach about your project in their communities — to develop learning and presentation materials and speak at meetups. You may have just found your most enthusiastic marketer.

This list is absolutely not the be-all and end-all for this topic; I’d like to know what approaches others use.

Example

Years ago, while helping new applicants to Google Summer of Code get into working on a particular project, I saw someone in IRC mention that he was having trouble and was trying to debug a setup issue. At that time, like many of our applicants, he was a student in an Indian engineering college. He seemed to be asking for help but not systematically investigating what the problem might be. So I said3, “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. 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 enthusiastically agreed with him! 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.

How to develop this skill

• Get experience with helping people who are new to contributing to FLOSS or who are early in their programming careers, in a setting where you have voluntarily chosen to do so, so that you can better notice and empathize. Mentor or organize events for GSoC/Outreachy, volunteer to help new folks learn at a local meetup, and run extracurricular events along the OpenHatch model.

• Study instructional design and learn how to teach via Carpentries instructor training, or (if you don't have two days to do that) do some of the exercises. If you are particularly dedicated to being able to grow new contributors, get some friends together and do the Teaching Tech Together training. This will help you figure out what mental models are prerequisites to success in participating in your projects, and how to teach those things.

Sumana's personal perspective

Different people get involved with open source software projects for different reasons. As ex-CIA agent Patrick Skinner says:

"The best assets I ever ran weren’t in it for money ... They had this urge to be part of something bigger. It wasn’t patriotism — they just wanted to be part of a high- functioning team.”

Some people are trying to get involved in your project because of personal goals (career, curiosity, etc.) that may be all well and good but have nothing to do with what your team is trying to do. Open source software is a "why don't you try" option that people find, or get a suggestion to try, as a new alternate pathway out of the precariat. If what I'm saying is hard for you to understand, or if you are an American and think, "Why don't they go to college?" then Tressie McMillan Cottom’s book Lower Ed will be an informative read for you.

Key takeaways

• Systematic thought and experience can help you figure out the steps that will take someone from "poor contributor" to "teammate".

• As long as you are kind and consistent, it's okay and in fact welcome to redirect contributors.

• Fairness does not demand that every project welcome every contributor's work in every area.

References

This is based on material posted on my blog in 2017 and in 2020. Thanks to Noah Swartz for starting a conversation at Maintainerati that spurred me to write much of this.

Related chapters you might like

If you find this chapter useful, you might like chapters in the full book such as:

• "Managing contributors who need guidance"

Other important aspects of contributions — like, did the contributor feel respected by the community, and feel like they made an impact? Sometimes a small but visible and immediate result feels more rewarding than a "large" but slow-to-deploy or invisible-to- user patch. And did the contribution result in the contributor learning and installing/running more of the necessary infrastructure to be a long-term contributor? This includes digital tools (Git, Docker, etc.) and social tools (subscribing to an email list, learning to use IRC, etc.).

• "Managing cadence shear among contributors"

Volunteer time is different from paid time, as Sue Gardner discusses in her great "A little guide to working with online communities". Lots of free and open source software projects exist as collaborations among mixed groups of paid and volunteer contributors. Often the primary stewards, the maintainers, are paid by a particular company, government, university or nonprofit. And those staffers have deadlines and priorities they need to work on. Staffers want to collaborate with volunteers, but volunteers' availability, interests, and skills are hard to predict, so it's hard to schedule for collaboration. When your team only wants to attract a certain kind of contributor/contribution, because some of the workers are paid staff working on projects with deadlines. It's as though your main workflow is a conveyor belt at a single speed; how do you usefully engage with volunteers who have very different speeds? And how do you do this without being super exploitative? Many, many FLOSS projects that have a lot of full-time paid staff working on the project — and which wish to also collaborate with people who don't have as much experience or time to devote — end up with this kind of schedule and expectation shear.

An outline of the full book

• Introduction

I. Settling in

• Taking initial project audit/inventory • Informally conversing with the people who brought you in • Taking on routine responsibilities • Triaging bug reports • Updating obsolete documentation • Cleaning up the code review queue • Understanding conversation platforms and expectations • Building trust: Demonstrating credibility, fairness, trustworthiness • Mapping your position • Placing your project in context (driver vs. supporter, the innovation S-curve, strategy) • Conducting a SWOT analysis

II. Taking charge

• Running meetings • Setting priorities and making releases • Replying to issues that require diplomacy • Dealing with existing budgets • Managing rhythm mismatches (cadence shear) in participation • Noticing and dealing with people problems • Guiding Contributors who need guidance • Working with neuroatypical people • Teaching and including unskilled volunteers • Coaching and excluding toxic people • Understanding and dealing with usurpers • Helping flighty colleagues

III. Making change

Infrastructure-building: social, digital, financial, legal

• Social • Using and improving mentorship programs (such as Google Summer of Code and Outreachy) • Using in-person time well • Adding/improving Codes of Conduct, governance, and related changes • Developing a Requests For Comment process • Improving user (stakeholder) communication and listening channels • Digital • Improving bug tracking & other user support interfaces • Improving code review & related workflows • Financial • How to start thinking about budgets and money • Writing grant and other funding proposals • Considering crowdfunding and drip funding • Legal • Getting an organizational home

IV. Passing the baton

• Assessing sustainability • Finding your successors • Saying no and responsibly stepping away (including realizing WHEN to do so)

V. Endmatter

• Appendix A: Release management assessment framework • References • Acknowledgments

Acknowledgments

Thank you to everyone who helped me on the path to this book. In particular (and my apologies if I have overlooked you):

Thanks to my editor Julia Rios, who has improved my prose and who has laid out, designed, and produced this book. And thanks to my researcher Audrey Eschright, whose literature survey has helped me decide what to write. Thank you to so many people who encouraged this book and shared their thoughts, or whose conversations with me spurred chapters: Karl Fogel, Julia Evans, Noah Swartz, Brion Vibber, Andrea Phillips, Dr. Gus Andrews, Dr. Linda McIver, Dr. Nick Murphy, Dr. Zack Weinberg, Pradyun Gedam, Laura Hampton, Tim Abbott, Emily Herzlin, Luis Villa, and so many others, including people I spoke with at the Recurse Center and at Open Source Bridge. Much appreciation to my parents and to my sister, Nandini, who have always encouraged my writing. And, of course, thanks to my spouse, Leonard Richardson, who steadfastly believed in this much-delayed project, and in me.

About the author

Sumana Harihareswara is an open source software contributor, programmer, and project manager with over fifteen years of experience in the software industry. She led the rollout of the new PyPI.org in 2018, and has worked on maintenance for Zulip, HTTPS Everywhere, Mailman, MediaWiki, and several other open source projects. Most recently she has managed improvements to pip's dependency resolver and user experience, and has expedited the release of new versions of pipenv and autoconf. Harihareswara frequently speaks and writes about open source and management, keynoting conferences including LibrePlanet, FLOSS Community Metrics Meeting, and Open Source Bridge. Prior to founding Changeset, Harihareswara was Senior Technical Writer and Engineering Community Manager at the Wikimedia Foundation, leading MediaWiki contributors. She has also managed projects at Collabora, GNOME, QuestionCopyright.org, Fog Creek Software, Behavior, and Salon.com. Harihareswara served on the board of directors of the Ada Initiative and currently serves on the Otherwise Award Motherboard. Harihareswara is a member of the Python Packaging Authority and of the Python Software Foundation's Packaging Working Group, and a cofounder of the PSF’s Project Funding Working Group. She holds an MS in Technology Management from Columbia University and a BA in political science from the University of California, Berkeley. She is a certified Software Carpentry and Data Carpentry instructor, and she participated in the Recurse Center in 2013 and 2014. Her past leadership in nonprofit, academia, industry, and volunteer organizations earned her an Open Source Citizen Award in 2011 and the Google Open Source Peer Bonus in 2018. Harihareswara lives in New York City and founded Changeset Consulting in 2015.

Feedback welcome

This is a sampler

This book is a sampler to give you a taste of the full book. I welcome your feedback, which will help me make the final book better. Have you solved any of these problems in a different way? Would a different structure help you better? Did any of my examples or phrasings particularly ring true? Please email [email protected] with "Unstuck" in the subject line to tell me what you thought.

1 The CC BY-SA 4.0 license means you are free to:

• Share — copy and redistribute the material in any medium or format.

• Adapt — Remix, transform, or build upon the material for any purpose, even commercially.

Under the following terms:

• Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.

• ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

• No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

For full legal wording of the license, see https://creativecommons.org/licenses/by-sa/4.0/legalcode

2 "Grassroots" here meaning that it did not start sponsored by an institution; see my personal perspective later in this chapter for more on general categories of projects.

3 I don’t have the logs from this conversation, so this is a recollection and not a verbatim transcript.