Sumana Harihareswara - Getting unstuck: Advice for open source projects

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.

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 Stckli

For Leonard, my foundation.

And for Aaron Swartz, our lighthouse.

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

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

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.

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 cant count on that leverage.

Basic assumptions about open source and the tech industries

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.

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.

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 thats not a problem, as long as folks with complementary skills can join in and co-lead these projects with them.

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:

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: