Everyone is using open source software now but most people have not figured out how to interact effectively with the open source software community. Mike McQuaid explains how to improve your open source software interactions whether as a user, contributor or maintainer. This talk will teach how to get the open source community to work with and for you to succeed in your goals.
← All talks 
Build Engineering Turing Fest 2017
Effective Open Source Interactions
Auto-generated transcript - may contain errors. Tap a timestamp to jump the video.
Right. We're having a good start because I managed to do the novice thing of putting my speaker notes on the screen before. So you may have seen that there's one of the first things in my speaker notes is telling myself not to say or like.
So if you decide to count how many times I say either of those things, then I guess email me afterwards, and I'll make sure to file it appropriately into my trash. Right. So it was great talk from Anna before. Like, just a little side note that Gov.
UK is more or less, like ten years ago or maybe when I was in uni. I used to rant to my friends at the pub that this is how we should be doing. Government should be open source and stuff like that, so it's nice to see that that's actually becoming a reality now.
I'm coming at this topic of effective open source interactions with two different hats on. So one hat I wear is I'm the lead maintainer of Homebrew. How many people in here have used Homebrew or know what it is or anything like that? Okay, a reasonable number of people.
Anyone who doesn't, it's like a package manager for Macs. So it's ways of installing all your development dependencies and stuff like that that you care about. So I've been working on that for what to say about eight years now. And that's I guess taught me most of what I know about like open source at like serious scale and we'll talk more about that in the talk.
So the other angle I have is I work for GitHub. So who uses GitHub here? A reasonable number of people. Yeah, so I've been working there for about three and a half years and I'm focusing on open source there. So my goal there is without just directly changing the product all the time, how can I make GitHub better for open source and people wanting to contribute to open source and people wanting to maintain open source and stuff like that?
So if you have any ideas about that feel free to grab me at the conference. Feel free to speak to me on Twitter or email or whatever. So I'm going to walk through today four different sort of stages of thinking about effective open source interactions.
So the first thing is I think it's helpful to think about in open source the different groups of people and how they get involved. So we're gonna kind of group users into different like categories of open source participants. The next is the funnel.
This used to be like a talk title I used in the past which was horrendous is the open source contributor funnel. And I'll introduce you to that later on. And we'll talk about how users kind of move between different areas of participating in open source.
Then upsell about how if they don't just move by themselves you can sometimes give them a delicate shove between areas they may or may not want to work on yet. And then finally how you can help out regardless of whether you're just using open source on a day to day basis or whether you're maintaining a large open source project.
What are the things you can do to make your life a little easier? Right, so let's have a look at the groups of people. And I think the most helpful way of thinking about this is asking yourself, okay so for any given individual, how are they interacting with an open source project?
So the first group I'm going to think about are users. So who here again, I'm going to do a lot of hand raising I'm afraid and some of it is going to be obviously patronizing that everyone's going to stick their hand up, but you know, indulged me anyway.
Right so who here has used open source software at some point in their life? If anyone didn't put your hand up you're probably wrong. So most people nowadays, I mean particularly most developers, I assume most people in here are engineers or at least interested in engineering.
I mean open source is more or less one. Know we're all using primarily open source tools most of the time. Even things like C and the Microsoft ecosystem is increasingly becoming open source now as well. So we're all familiar with using open source software and we're all familiar with going on GitHub and seeing how these projects are run and then having problems and maybe filing problems with those projects.
So when I'm talking about users here, I'm talking about a subset of the people who use open source software who are just users. So thinking about the type of people who maybe use open source software, they read the docs, if they have a problem at most they might submit an issue and say okay here's the problem I'm having.
Those issues can be pretty variable in quality. It can be anything from like literally I got an email the other day saying, help. I no use tool anymore. Help uninstall. Thanks, bye. So I wasn't quite sure what to do with that. And then you get some people who are technical users who make really, really great issues but aren't interested in resolving them themselves or kind of working on a fix.
So I'm copying those as users. So let's have a little think about what do users want for software in general, but open source I guess in particular. So they want their software to be high quality obviously, who doesn't? They want to be able to just go along and use the software and have it work the way they expect it to work.
And particularly I guess with the high quality that sort of segues into the next point which is that they want the next versions of the software. They want to be able to upgrade their software be it a Ruby Gem, NPM package, something they install with Homebrew, something they manually download off the internet or auto updates or whatever.
And they want the expectation that a new version is not going to break all of their workflows. And that's what I say with no v2.0. So I'm a little bit contentious with this in times. With home room maintainers I often argue, because people have all these ideas for like oh if we break backwards compatibility, here's all these cool things we can do and we can do it all right the next time or whatever.
I've seen so many open source projects make that type of mistake where they say okay well we made all these mistakes in the past, we're gonna throw away all our codes, we're gonna rewrite it all from scratch, everything's gonna be great and perfect and wonderful.
And what ends up happening is they obviously have hundreds of times more bugs because all the nice bugs that they fixed over the last years, they maybe remain fixed in the new one, but then they have a bunch of new bugs which are all broken now.
And also for their users, if you force all your users to relearn how to use your software, then it's just as easy for them to move to a competitor. And in the open source world, a competitor can be another library that's doing things better.
Or often in open source someone will go and just fork your old version and continue to run that that you don't want to run anymore. And you will frustratedly look as that boat sails off into the distance with all your users. And the final thing is people want to work.
When I say work quietly, what I mean by that is again related to the two previous points. People want to use open source software and not have to interact with your project. Ideally people want to be able to just have everything work exactly what they expect.
They go and look in the docs when they have a problem and it's documented just there exactly what they need to do and then all is wonderful. So moving on to the next group of people. So this is when people step up and maybe want to get a little bit more involved.
So I'm gonna talk here now about contributors. So who has ever contributed a commit, pull request, anything to an open source project? Cool. Probably about half the room I reckon. Maybe a little bit more. So these are the people for whom open source is something they tend to be a little bit more passionate about or it's just a transactional thing where I have a bug, I want it to get fixed, it's not getting fixed, I can fix this, I'm going to go and fix this.
So what I'm talking about with contributors is not everyone who commits to a project, not everyone who works on a project, but the people, the subset of those people who do not have access to write to the project directly, but they come along and they submit a fix or whatever.
So these are the people who I guess are step above users where they're probably using the software already, but then they've encountered a problem. Then rather than filing an issue or finding that there is an existing issue that was filed four and a half years ago, they take it upon themselves to go go to Noble Quest to go and fix the bug, submit a pull request, and then hopefully everything gets nicely merged.
So contributors generally want, they want good pull request review. I'm generally gonna use GitHub parlance and assume that everything's on GitHub because a lot of it is. But I think most of these principles apply elsewhere as well. But they want, when they submit their pull request, they want good review.
And by good review I mean they want I guess the stuff that Anna highlighted earlier as well. They want it not to be pedantry about tabs versus spaces or whatever. Like that stuff should all be automated away partly because humans respond better to bots being pedantic than other humans being pedantic.
And partly because it's nice if I can go and check all the pedantry sorted on my local machine before I have to kind of push it to the project. And they want that review to be kind of nice and friendly constructive and helpful and appreciative and not mean and pedantic and yuck.
The next thing they want is timely review. Like again, this is it's tough for open source maintainers, but in general we have really really good data now from Mozilla. There's a study recently where the single biggest thing that impacts whether someone is going to stick around on an open source project is how quickly they get response to their review.
If you submit a pull request and you get someone who comments, gives you feedback, you can then address that feedback and then you commit back. Then they address it again and say this is good to go. They merge it and they deploy it to production within a day, then you have a very positive experience.
If that takes a year or a year and a half, then chances are next time you think there's an issue with this project, you're not gonna be wanting to go through the same amount of process because it's not been as valuable for you.
So I think that's really important for both projects to consider, and also individuals to think about, although we'll touch more about this later, about how you can ensure that you can get that timely review by checking as many boxes as you can. And the final thing is they want earned praise.
And by earned praise, mean they don't want to just get congratulated like a puppy for every single time they don't poop on the floor. But they want to make sure that you know when they've done a good job, they want to be told, You've done a good job.
Well done. And to have appreciation for the work that they've done. So the final group of people I'm going talk about is maintainers. So by these, these are probably people who use the software. They're people who contribute to the software and probably are still contributing to the software, but these are the people who their main thing is having commit access to the software.
So their job is to kind of wrangle community contributions, deal with user support requests, basically just make sure the project keeps running. So it tends to be quite a sort of like multi hat job, particularly in sort of mid sized projects where they're providing user support, they're writing new features, fixing bugs, prioritising bugs, and then providing decent code review and deciding whether or not to merge people's contributions.
What maintainers tend to want in projects is, first thing is no bike shedding. Who's familiar with the term bike shedding? Most people. But if you're not, it's the idea that if you want someone to go and you know provide architectural view on your multi agent distributed system, then you may not find many people in your organization who do so.
If you want to find people who will discuss with you what colour the new office bike shed should be, everyone all of a sudden has an opinion. Because the barrier to entry on that discussion is incredibly low, and everyone can just say, well I really think it should be red.
No, I think it should be blue. Whatever. And in open source, these types of conversations are sadly common, where things which it becomes not a discussion of the code, but just a relatively common one is a discussion that we all agree that something is bad and something needs to be done.
And there's just comment after comment of people saying something needs to be done. I agree. This was bad. Something needs to be done. And that's obviously when people yeah, plus one plus one plus one before GitHub had reactions. And the thing with that stuff is that's time that the maintainers and contributors are spending reading, responding to those comments that they can't spend actually working on the project.
Ultimately, the maintainers, although it's fun sometimes to argue with people on the Internet, ultimately they primarily want to be making the software better. To do that requires them to have that time to be able to spend to sit down, write a fix, write a new feature to address the problem.
The next thing I think is really helpful but can sometimes be a little contentious is maintainers generally want some sort of private chat between themselves. So if I disagree really really strongly with another maintainer on my project, it's more helpful for me to be able to work through that strong disagreement in a private setting and then post the conclusion of our conversation publicly.
And it's basically just because you know people can, particularly when stuff's in the public, people can sometimes be more touchy, more sensitive, and it's like harder to phrase things in a way that is sometimes very clear, but maybe not too strong, but sufficiently strong, etcetera, etcetera.
So I think those types of private chats are really good at resolving conflict and also building a little sense of community. It's nice to have for maintainers to have their own sort of private safe space where they can kind of chat about things and sort of build up friendships and rapport without that all needing to be on a bug tracker.
And the final thing, which I'll lead on to more about this, is they want more help. Almost no maintainers in open source are going to stick around forever. In Homebrew, I've been working on it for eight years. I wasn't the first maintainer, but I'm by far the longest one who's kind of stuck around.
You need to always be thinking about how are you going to get more people to help you build this project and how are you going to get someone to replace you. So both when you want to leave, you can do that, but also if you get Who's familiar with bus factor?
So bus factor being how many people in your project can get hit by a bus before your project can no longer function. So trying to ensure that the bus factor of your project is larger than one is a good thing to do. So the next thing is thinking about the funnel.
So obviously I guess you've seen a little bit, I've been kind of leading from this already, that you have users, contributors, maintainers who kind of escalate in their level of involvement, and you probably have enough experience yourself to know in most communities as well, they decrease in their numbers.
So this is what I'm thinking about with the funnel. So a few statements to start with. So no one ever became a contributor without being a user first. I'm sure in some cases this has happened in the past, but in generality people are contributing to open source software because they're scratching their own itch.
People familiar with scratching your own itch? A few people. So Anna noted that as well. So scratching your own itch is the idea that in open source the best way to get started is not to go and find a project which has an open issue that you can go and write some code for because frankly that sounds a bit like homework and I intentionally left university a long time ago for a reason.
And what's more interesting generally is being like okay I have a particular problem. I use some open source software. This problem is in this open source software. I'm going to go and fix my own problem. And that's referred to as scratching your own itch.
So in general that's where most people end up contributing from. They're a user, they see a problem, they want to fix the problem, they scratch their own itch, and then ta da, they're a contributor. Similarly, no one ever became a maintainer without being a user.
In general this is a thing where people don't just appear in a project and get access to maintaining the project. People generally have to contribute a bit first, they have to use the project a bit first. And in general, it's not very common for people to say, please make me a maintainer, please make me a maintainer.
And that's generally a bad sign. Generally, I found most of the people who become very good maintainers are the people who you have to continually battle their imposter syndrome for the first few months and say, No, you are good enough. Yes, we want you to help. Please help us.
And then they kind of join the project and help you out. And then finally, no one excels as a maintainer without remaining a user, and that relates to what I said before. There may be a time when eventually it's time if you're an open source maintainer for you to step away from a project and go and move on.
Speaking of which, how many people in here would say they maintain any sort of open source project in any sort of fashion? Okay. Probably a quarter of the room. So at some point there's going to be a time if you are maintaining a project, even if you're not doing so today, where you're gonna want to step away.
And in my opinion the time that that should always happen is when you're no longer using it. If you say made some library for work or whatever, some Ruby gem to solve a particular problem and your workplace used it lots, and then you changed jobs, and you're now writing Node and JavaScript and whatever, then it's probably not that helpful for you to continue to try, unless you're really enjoying it, to continue to try and maintain that library.
You're better to try and hand that off to someone who's actively using it, someone who understands what the users are experiencing, and someone who can follow the kind of the changes that are happening in that language ecosystem, rather than forcing yourself just because I created it or I maintained it or whatever that I have to do so in perpetuity.
Right. So this is I believe. Is anyone here a salesperson, or has that ever done any sales? Almost no one. Great. So no one's gonna call me on probably being wrong. So this is my understanding what a sales funnel is. You start with leads, and then you have prospects and then sales.
So leads are like people who are notionally interested in buying your thing. Prospects are the people who've actually sort of engaged with some sort of, engaged with a salesperson or whatever and started a conversation and then sales being the people who've actually handed you some sort of money.
And my idea is that actually open source is kind of vaguely similar in terms of if you're looking at maintainers as the goal, where you have users being the people who have not really they've shown interest in your project, but not really any interest in maintaining your project or contributing or anything like that.
You have contributors who are the people who've been involved, maybe intermittently, maybe just as a one off, but you're kind of there the next step to becoming maintainers, which are the people who are involved on a day to day basis. So to read out some numbers because the funnel is fairly sharp in Homebrew's case.
So we have, I reckon about one point two million homebrew users. Google Analytics says about four million but there's like bots and CI machines and stuff like that in that. In all time we have like six thousand ish homebrew contributors. That's zero point zero five percent of our users.
And today we have sixteen homebrew maintainers which is zero point zero zero two five percent and a total of like twenty five maintainers in lifetime. So you can see like I don't think all projects are going to have numbers that are quite that sharp.
Obviously it would be kind of depressing if every project required you to have about one hundred thousand users for one maintainer. But I guess it's worth stating because it shows that this type of funnel and trying to push people between it is at least partly a numbers game.
The more users you have, think the more contributors you're going get, and the more contributors you get the more maintainers that are at least potentially out there. So let's talk about like upselling people. So in the sales funnel, you're I guess trying to convince people to hand over money to you, whereas in the kind of escalating contributor funnel, you're trying to convince people to hand over time and care to helping you out in this project.
I guess it's technically like a down sell, but I couldn't find an emoji that's pointing down, so there you go. So start with a statement for that as well. I guess I alluded to that earlier, but most maintainers get talked into being maintainers.
Most don't want to do it. It's not something they really aspire towards doing, but they are just people who become helpful in a project over a reasonable period of time, and then as a result they get asked, would you consider helping out more formally with the project?
And joining us and helping us triage things and merge PRs as well as reviewing or committing or whatever. So this is an example of upselling a kind of slightly apologies to this person in particular, but a not great bug report into maybe a better one.
So we've said to them, Okay, rather than your one hundred and forty character issue on Twitter, could you maybe consider opening an issue on our GitHub repository? And then that will walk them through the issue template, some guides as to how best to do that.
So then sometimes if we get an issue, then you can like, this is one of my of canned replies that I use to try and nudge people towards, okay, let's understand exactly what you're doing and what went wrong and why. This is also, as long as none of you promise to tell my co workers, this is useful sometimes as I can reply with co workers as well who don't adequately explain their problems.
The next step beyond that is trying to upsell when people are submitting good issue reports and they seem kind of like fairly savvy and engaged. Then this is another one of my little can replies to try and upsell them to a pull request.
So we have a nice little guide for how to open a Homebrew pull request that sort of walks people through step by step. There's diminishing returns with stuff like this and the level you can go to in terms of we try and help people who maybe aren't that familiar with Git and GitHub to sort of know what commands they should run.
I guess a coworker sort of elaborated on this as being whether you're trying to help people on how to GitHub, how to development, how to computer. I think how do I even computer is a little bit beyond my realms of being willing to help with.
So in general, we assume people who want to contribute to Homebrew or are contributing have a development background and are able to at least know their way around editing some code. And then we just want to make docs to kind of help them as much as possible.
We also have, you can probably see in the middle here, like a single command. If you're doing the most common pull request we have, which is like upgrading the version of a package that we have, then you can literally do that with a single command that will open the pull request for you.
And that's sometimes again fun for people as their first contribution is being like that was almost entirely automated for you. And then people can move to more complex contributions later. We also have a new maintainer checklist. Again this is sort of documenting the way that people go from being contributors to being maintainers.
And this kind of walks through like what we look out for and then the emails that we kind of tend to send people to ask them to be maintainers what that part of the process looks like. So let's move. I guess we've seen these different users, how we can kind of move between them.
So wherever you might find yourself, let's see how you can help with open source and have better interactions with open source projects. So in general as an open source user, I think the important things are to firstly have reasonable expectations of that project.
I guess Anna touched on stuff before. I think projects are getting better now at setting expectations of how much support you can expect to receive. It's very important to remember that particularly you know developer tools you might use very often like Homebrew for example, No one is paid to work on Homebrew even like part time.
Some people are able to kind of carve some little bits of time out from their employer to work on it. But there's no organization or corporation backing Homebrew. Homebrew has four digits of money in the bank from a Kickstarter we did a few years ago and stuff like that.
So we just don't have the resources to be able to help every single person to the level that we would like to. So you need to have expectations when you use tools like that, that if the developers can't reproduce your issue on their machine, chances are they're not going to be able to invest a huge amount of time into fixing it.
The next thing is help how you can. That doesn't mean everyone needs to be a maintainer or a contributor or submitting huge amounts of pull requests or whatever, but it means if you're filing an issue or whatever, try and take the time to really think about how to explain your problem clearly.
Make sure you of on the side of providing too much information, and I guess this is the main, my main minor rant is like the little issue template that GitHub issues have. Please always fill that out. A lot of people think they know better than filling it out, but chances are the maintainers have asked for that information because they need that information.
And finally, which relates to that, prioritize maintainers' time. As I said before, Homebrew has maybe a million users. Even though it's a factor of ten less than that, like say ten thousand users, even if it's one hundred thousand users, ten thousand users, whatever, it's still way way way more users than there are maintainers.
So maintainers need to be able to prioritise what they work on and when, and as a result we need users to help us in that prioritisation. Next, as a contributor you should always try and follow the project guidelines. By that I mean try and read the docs, try and read the contributing file, try and read the code of conduct and stuff like that, and run any test suite you have locally and stuff like that.
Just to make sure that again you're not having to go through a dance where people are telling you to read the output of the tests and stuff like that. It's helpful for everyone I think if you can try and do as much as you can upfront.
Obviously sometimes you'll miss that and that's no big deal, but putting them in that effort is really helpful. The next thing is deferring to maintainers. This doesn't mean that maintainers are always right, but it does mean in the context of a project like homebrew, for example, if it's your first pull request to homebrew and if you end up in an argument with a maintainer of homebrew who's been working on it for five years, chances are they're kind of winning that argument by default because they have the choice whether to commit your
stuff or not, and you don't have the choice whether to or not. So although you may not like what they say, generally following their advice sooner rather than later makes all the communication a little smoother. And finally being willing to go outside your comfort zone.
The example I tend to use for that is my first contribution to Homebrew, Homebrew was all written in Ruby from day one. And I had never written a single line of Ruby before touching Homebrew. So I started with making like a couple of character line changes and then a couple of line changes and then editing Homebrew's code itself.
And like now for the last I guess five years I've been writing Ruby for a living. And I learned Ruby through Homebrew. And if people hadn't nudged me to kind of start using Ruby to learn, to be able to contribute to Homebrew, and start learning more about Ruby to be able to make less silly bugs in Ruby, then I wouldn't have I probably wouldn't have the job I have today.
So as a maintainer, again three things. So the first is self care. Like if the sky is falling, if there's some really big bug that has caused a lot of users a lot of issues and a lot of people are very angry, it's important to prioritise looking after yourself.
Because whether people articulate it or not, they would rather have you continue to work on the project than necessarily fix their problem right now. So sometimes that means just walking away from the computer and going and seeing a friend or having a drink or whatever helps you deal with the stress of open source sometimes.
The next thing is acting as a force multiplier. Again, as a maintainer, if there's lots and lots of users and lots and lots of contributors, what you want to try and do is spend your time on the stuff that people can't come along and trivially do for you.
You want to spend your time trying to enable other people to work on homebrew or enable sorry other people to work on whatever your open source project is. So I try and spend a lot of my time now working on tooling and working on the things that other people aren't gonna do, rather than doing too much in the way of fixing bugs that other people can fix.
And then finally focusing on ninety percent of your users. I guess this is a general product comment anyway that it's kind of nice to focus on the majority of people working on and using your software rather than the tiny use case of a maybe a very vocal minority.
And then this will help you prioritise your time and prioritise what issues you're going to work on as well. Final little plug. This was built by some people at GitHub, but it's all open source. The open source guides, this is a really good resource for getting people involved with open source, learning some basics about maintenance and stuff like that.
It elaborates on almost everything I've touched on in this talk like to a much higher degree. So I would recommend going and checking this out. So we walked through the different groups of open source users. We've got users, we've got contributors, we've got maintainers.
Talking about how the open source contributor funnel means that they can work from top to bottom and come out the bottom as lovely maintainers. How to kind of gently nudge people between them with issue templates, with documentation, with canned replies and stuff like that.
And then finally all the different ways in which you can help out as interacting with open source projects. So thank you very much for having me. I'm Mike McQuaid. You can email me or tweet me or whatever if you have any questions or thoughts.
And thank you very much.