Don't drown in your open source project!

I presented Just Keep Swimming! Or, how not to drown in your open source project at DrupalCon Baltimore 2017, as part of the Being Human track. Below is a text summary of the presentation (along with the associated slides).

Here's a video of the presentation; scroll past it to read through a transcript and slides:

And the slides/transcript:

Hi, I'm Jeff Geerling, known most places around the Internet as geerlingguy. I've been involved with the Drupal community for almost nine years, and the Ansible community for four. I work for a company named Acquia, one of the largest Drupal service providers, and I write a lot (mostly about open source software), and automate a lot of things (mostly using Ansible).

I do a lot of open source work. I maintain over 160 independent open source projects on GitHub, and help with a few others. Some of these projects are pretty tiny, but there are a number with hundreds or thousands of stars, and thousands of issues, commits, and pull requests.

My biggest claim to fame is that I'm the highest ranked open source contributor in St. Louis. That's gotta count for something, right?

But my open source work is just one small part of my life. I'm also a husband and father of three kids—a four year old, a two year old, and a six month old. In this picture, you can witness one of the common rituals in the Geerling household (those of you who don't have kids might be wondering what I'm holding): the changing of the diaper pail. Between dealing with toddler meltdowns, activity time, changing diapers, and family game nights, family is an important part of my life. A lot of the reason I do the work I do is for my family: I want to make sure my children have the tools and time to do more than I could imagine to make the world a better place. Family is extremely important, and other things in my life often take a backseat to family matters.

I also spend as much time as I can taking pictures and exploring photography. Before I decided to work in software development full-time, I was splitting my time between development and photojournalism, and I still take on a few paid gigs every year. This year, in fact, I'm taking pictures in a semi-official role as a volunteer photographer at DrupalCon (you may have seen me sneaking around with this massive camera!).

I also enjoy DIY projects: in this picture, contrary to what you may be thinking, I am not building a meth lab. I was building the home office in which I've been working for Acquia. I work on projects around the house, I help neighbors with their own projects, and I even enjoy light gardening—even though almost all my perennials seem to die every year.

Finally, something that impacts me on almost a daily basis is my Crohn's disease. It's a chronic, but not fatal, disease, and I've been dealing with it since 2003. This picture is from about six months ago, when I had major surgery to remove part of my gut. Even then, I was thinking about Drupal, ha!

I'm doing pretty well today (thanks for your concern!), and having to deal with the ups and downs of Crohn's disease has really made me feel thankful for the times when I can be productive (in work, in family time, and in open source), and more importantly it is a constant reminder that you never know what someone else is going through, so I know it's important to always treat others with compassion and assume the best intent.

The point is, I'm a human. I have human needs and desires. And the same for all of you. All open source maintainers, contributors, and users come together and bring their own relationships, experiences, and struggles to the table.

Often, when someone is struggling in life, open source work (often being one of the less important aspects) is the first thing to go. That's a major reason why all open source maintainers have a constant battle with burnout. Once open source work becomes a struggle and a burden, it no longer rewards maintainers with doses of optimism and euphoria that sustain their involvement!

This chart shows the time I spend doing various things through the day. It's not a ranking of importance, just the amount of time spent, on average, doing each thing. I spend almost all my day either working (that's the W-2 section), sleeping, or being present to my family. Then there are some things like eating and reading (or, let's be honest, binging on Netflix or Reddit!). Then there's the last slice, accounting for about 1.5 hours a day, that I choose to devote to Open Source work.

Most open source maintainers are in the same boat. Most of us aren't paid to work on our open source projects during work hours (though sometimes we're fortunate enough to be able to devote some time to them), and most of us have only a small amount of time to devote to open source work. So it's important that we use that time well, and focus on tasks that don't drag us down and make us dread the work. We have plenty of W-2 work during the day like that!

So I'm going to show you what that small slice of open source work looks like, on an average day.

I often start my time glancing at my 'open source' email folder.

YIKES, that's overwhelming! Well, maybe I'll change gears and just focus on my GitHub issues.

Hmm...

This constant barrage of notifications can be really jarring. It's probably best to ignore the common notifications, and find a way to filter out issues that are not as important or wouldn't be a good use of your time.

Let's jump into an issue queue and find a pull request or patch to review.

Nice! It looks like I stumbled upon a rare breed of GitHub pull requests: this PR has the four hallmarks of a pull request likely to be merged:

1. There is a thorough description of the why behind the PR, how it works, and even a link to find further information! This makes it so I don't have to spend my hour researching the code changes—the contributor already did it for me.
2. This PR doesn't change everything under the sun. It's only adding a few lines of code, which means I will likely be able to review it quickly (certainly in less than 1 hour).
3. The commit history looks clean. There's one commit with a short message describing the changes.
4. The PR passes all the project's automated tests (so I know at minimum it doesn't break my project's existing functionality).

What a great way to kick off my open source time! If all the issues are like this one, I'll probably get through at least five or ten issues today!

... But then reality hits us. Very few issues, patches, and pull requests are so easy to resolve.

These examples highlight one of the most prolific issue types that will clog up your queues. Weeks go by with no response from the person who opened the issue, and you have no recourse but to close the issue with no definitive resolution.

Well, let me introduce you to some common issues and some characters you may run into:

These are Ghost Writer issues. A Ghost Writer is when the OP (Original Poster) disappears off the face of the planet, never to be heard from again. These clog up every major project's issue queues, and take a lot of time away while maintainers prune these dead issues out of their issue queues.

The next kind of issue I see more often than I'd like is by someone who apparently doesn't see the documentation, known as the See No Docs issues. When the OP asks a question that's answered in the first section of the project's documentation! And alongside are the Read No Docs issues (when the maintainer links to documentation but it's obvious the user didn't read them before replying again), and the Fix No Docs issues (when the issue mentions a small bug or improvement in the docs, but nobody ever files a patch).

Then there's the Iceberg issues. These are issues that look like they'll require only minimal effort to resolve, but once you get into them, you realize you just burned up a week's worth of your time trying to resolve the issue! There's a lot more to the issue hidden under the water.

Next up, you know that person who prods you to merge an old patch that passes automated tests but you haven't merged for some reason or another?

That's a 'For Shame'er. These comments are often unintentionally insidious; they usually have a slightly passive-agressive tone, and if you're not careful as a maintainer, these can really tear down your confidence. Most of us suffer from the Imposter Syndrome already, and when we see these comments, it makes us feel potentially more inadequate as a maintainer!

I'm not saying that bumping or +1'ing an issue is necessarily wrong. Rather, if you want to add your 2¢, please either stick to a "+1" comment, or make sure your statement doesn't have any passive-agressive undertones!

And then there's the Dung Heap. These issues are pretty easy to identify, and if you're like me and you're ruthless in cleaning up your issue queue, they don't stay long. Dung Heap issues are those that contain little or no description, hundreds or thousands of lines of changed code, don't follow your project's coding style, and often fails to pass automated tests.

There's no way you should consider merging these; just close them quickly and move on.

Closely related is the Diamond in the Rough: it's mostly a Dung Heap, but there is one change in the patch or pull request which is actually really good. Enough so that you don't want to close the issue, and you give the OP feedback asking to remove all the unrelated changes and resubmit.

But it seems these issues are often combined with a Ghost Writer (the OP never responds), and then after a month or two, you start getting a few 'For Shame'ers asking why this obviously brilliant change hasn't been merged yet.

There's also the Imposter. These issues are ones that have no real relation to your project. Instead, it's a poor lost soul who knows you've helped them in the past, so they post an issue only tangentially related to your project, hoping you'll answer their question out of the kindness of your heart.

And finally, the Black Hole. These issues start off unassumingly, with a simple premise and maybe a straightforward path to completion. But then someone suggests changing a variable name. Then, three hundred comments later, after the variable name is back to the original one, it seems there is no end in sight. Black Holes most often devolve into a Bikeshed, where people are arguing more over a variable name or a code comment than the actual change itself!

Whether or not you have kids, there's a chance you've heard of Dory, a Disney/Pixar character who has issues with short-term memory, but is a faithful companion and optimist. Dory offers us this simple advice: when your issue queue gets you down, you need to just keep swimming!

Let's not drown in our issue queues. Instead, I'm going to talk about some of the things that I do when managing all my projects. I hope you'll find some of these things helpful!

One thing that is often overlooked, but in some ways fairly important in increasing uptake and continued usage is to inject some personality in your project. If your project has some amount of personality, it can make both you and your users like and remember it better.

One example is the 'Raspberry Pi Dramble' logo (the one with the six Druplicons in the shape of a raspberry). After making the logo and sticking it on the Pi Dramble website, I started to approach the project differently. I tried to simplify some things and make the videos and documentation for it more approachable. It's a subtle change, but I think it's important. (Case in point, the venerable Druplicon.)

Another example is Drupal VM: I first created it as "A Drupal Development VM", but that name didn't really roll off the tongue well, was really long, and didn't endear users to the project. Once it got more popular, I took some time to:

1. Rename the project to, simply, "Drupal VM" — no "The". This made Drupal VM a proper noun, and also affected the language around the project.
2. Create a wordmark and use it consistently.

It's very hard to relate to projects that have no personality, and especially when things are rough, it's a lot easier to abandon something if it has no personality, no branding, no identifying marks.

This isn't to say branding is everything—but it definitely helps guide people's perception, and your own too!

Next up: Work in the open. I actually had a great example of this at a BoF yesterday—I was talking about a problem I encountered with Drupal but didn't know if an issue had been filed about it. Someone mentioned that an issue was in the Core issue queue, and when I opened it up and scrolled down, I had the most recent comment on the issue, from two months ago!

There are a number of benefits that come from documenting things as you go, and from blogging—or at a minimum, storing your thoughts somewhere public:

1. You can use Google to search your own brain!
2. If you start working on something but get stuck, or need to switch gears, someone else can pick up where you left off and push the issue through to completion.
3. Other people get their own problems resolved by seeing what you wrote. If it stays in your head or in a private journal, chances are nobody (including yourself) will benefit from the work beyond the immediate fix or feature you completed.

This slide I added just because I'm a Tesla nut.

No, I kid; the real reason is because of something Elon Musk said:

Tesla focuses heavily on designing the machine that makes the machine - turning the factory itself into a product.

Tesla is currently the largest automotive manufacturer in the US (by market capitalization)—even though they produce far fewer vehicles than Ford, GM, Chrysler, and other manufacturers. The reason for this is that people value Tesla's philosophy: automating things and increasing efficiency.

Most open source projects have a very sparse commodity: development time. And wasting development time on mundane, mind-numbing tasks like manual testing, code linting, etc. will quickly discourage potential contributors.

At a minimum, you should have a goal of automating:

• Code style / linting
• Functional tests (at least one 'happy path' test to verify things aren't horribly broken
• First-time setup (how long does it take a new contributor to be able to get a clean environment running your code? Docker can help here!)
• Notifications and email (e.g. route all OSS email into a specific folder, and don't let those emails show in your 'unread' count)

Additionally, if you find yourself asking for the same extra information every time someone posts a new issue, you can add an ISSUE_TEMPLATE if you use GitHub, and put required information and suggestions inside to ensure people posting issues provide all the right information.

As your project starts to grow, you'll start interacting with more people: users, potential users, and even (if you're lucky) contributors!

If you want to keep your project maintainable, there are some things you should do to foster your community and distribute responsibility:

1. Connect with fans: Often there are a few people who are willing to help or at least promote your project. Communicate with them, ask them to help, allow them to take on responsibilities if they seem aligned with your project's goals, structure, etc.
2. Give karma: Thank contributors in release notes, on Twitter, at events, etc. Open source is a volunteer-driven effort; if money is not available, gratitude is the currency of open source, so give generously and you'll have some passionate users and contributors!
3. Avoid drama: If you find some controversy brewing in your issue queue or elsewhere, take a step back and see if it quickly resolves itself. If you have to intervene, don't make a knee-jerk reaction, and make sure you're aware of the entire situation. If you don't have a direct role in the drama, my advice is avoid it. And always ask yourself the question: Is what you add going to be helpful?

I've spoken about a few of the things I find most important in being a happy and sane open source maintainer, but there's a wealth of information on the web on this topic. Almost every maintainer has to wrestle with the problem of staying afloat, and many maintainers put their thoughts into writing.

• Open Source Guides (from GitHub)
• Why I Haven't Fixed Your Issue Yet
• Why I close PRs
• What it feels like to be an open-source maintainer
• How I Learned to Stop Caring and Love Open Source
• Maintainers Don't Scale

I'd like to call out GitHub's Open Source Guides especially: these guides are great primers for so many different areas of open source contribution—for maintainers, for contributors, for users, and for businesses.

But what it all comes down to for all of us, is how we use our time. And what I'd ask you to remember is:

Thank you.