OSS from the trenches – 7 Tips for Maintainers & Contributors

Open source software simply wouldn’t exist without the countless volunteers who give of their time to contribute to projects. These volunteers are the maintainers, contributors and advocates that make the OSS world go round. Countless reasons motivate people to get involved: the need to fix a bug that is preventing them from from using their project of choice, the desire to build their public profile, and even just an urge to “giving back”.

While it may appear that its up to these contributors to take the initiative to put themselves out there, it’s important to remember that its also up to the project creators and maintainers to help pave the way. Obviously, the amount of effort put into this “path building” needs to be proportional to the amount of help the maintainers are after and the size of the projects, but it rarely happens all on its own.

Given my own experience of running Glimpse, I’m clearly pretty interested in how OSS projects grow and stay healthy, so yesterday I turned to twitter to see what project owners and contributors alike had to say. I got a lot of great responses which, combined what I’ve learned through Glimpse, I’ll try and summarise here.

Heads up: this is a longer post than most. It’s broken down into Tips for Project Maintainers, and Tips for Project Contributors. I think you get a better perspective if you see things from both sides, but feel free to jump to the bit that you want to dig into.

7 Tips for Project Maintainers

There are a number of things projects maintainers can do to help encourage people to contribute, and to make it as simple as possible to get involved. As Jeff Handley of Nuget mentioned when asked, most of this seems to boils down to four simple steps:

  1. Easy on-ramp.
  2. Embrace.
  3. Recognize.
  4. Recognize…again.

A lot of the great thoughts and suggestions that got sent my way fell into one of these steps, but there are actually some very interesting (and more explicit) tips to bear in mind.

#1 Don’t be afraid to ask for help:

Its amazing how many people will lend a hand if you ask them for help in an area that they are knowledgeable about. This usually works best if you have a specific task or goal in mind, and an idea of when you would like it completed by. If approaching someone for the first time, also ensuring it’s a relatively small task that makes it easier for someone to say “Yes” when asked!

#2 Yell to the heavens when someone commits:

Unless you have specifically been asked not to do so, it’s usually advisable to use as many avenues as you have to thank people for their contributions (regardless of size) and publicly acknowledge them. Typically with Glimpse, we use our release notes to mention anyone who has contributed, and even go as far as mentioning those who submitted bug reports. We also try and thank our contributors by name when referring to features they have build or contributed to in talks, presentations and documentation.

Any time we have done this, our contributors have thanked us many times over and gone away with a massive warm fuzzy feeling – and this is exactly how we should be aiming to make our contributors feel. From here, they might go on to share what they have done with colleagues, or even gain the confidence to speak at user groups and contribute to other open source projects.

#3 Present front-and-center how people can contribute:

When someone has the desire to contribute, it’s important that they be able to understand how your community operates, what they can expect, and places where you could use some help. The best tool we could possibly offer is to make it clear what issues are currently the top of our priority list, marked using the “Jump In” tag that Nik Molnar brought to the table, presented with a few crucial requirements. As outlined in Nik’s post, these listed issues have the correct phrasing in that it doesn’t imply that something is necessarily simple or only for beginners. And about those crucial requirements:

  • Don’t swamp people by having too many issues in the list.
    • Its easy for people to get lost in the sheer volume of tasks that could be picked up, so having a concise list featuring a range of different tasks is a good place to start.
  • Keep the list up-to-date.
    • Nothing is worse than a list that is out of date or doesn’t represent your current needs. Ideally, the list you present people in the project site be synced with the issues that have that tag in GitHub.
  • Make sure these details can be easily found on your project site.
    • Ideally you would have a dedicated page on your site that is referenced everywhere that users can navigate to.

#4 Let people know what the expectations of your community are:

As a contributor, it would be fantastic to know what sort of turn-around I can expect when I submit a Pull Request for a feature or an issue. When you provide this information, if reassures the contributor that their Pull Request won’t be left for months on end without any feedback. Ideally you would even have a data point on your “contributor information” page which shows the average time to Pull Request acceptance or first response from the maintainers.

#5 Tell contributors the rules when it comes to contributing features VS fixing issues:

Within Glimpse, I love it when an unexpected Pull Requests come in. At the same time, I occasionally hold my breath waiting to see the size of the request and whether it’s to fix an issue or contribute a feature. Typically an issue fix is a slam dunk, as it only modifies a limited amount of code. On the other hand, a new feature could contain any number of changes and additional classes, and when that appears unexpectedly, it can be a lot to digest and fold into the code base.

In our case, it’s our responsibility to tell contributors that issues are fair game to start off as pull requests, but that we like to start off new features with an Issue so that we can talk about the approach, architecture, etc., lessening the surprises later on. You may prefer everything to start with the code and Pull Request in your project, but you should at least tell people about how you handle things.

#6 If someone commits an issue, ask if they are interested in making the fix:

In an ideal world, it would be amazing if people fixed their own issues and sent in pull requests, but in reality we naturally don’t expect everyone to do this. That said, given the chance, more people than you might expect would try contributing a fix if asked and provided a few helpful pointers…

#7 If using GitHub, setup your CI server to build Pull Request as they come in:

GitHub has the ability to notify interested parties when Pull Requests come in. If you setup your build server to listen to this (like we do on Glimpse with TeamCity), you can have the build server not only compile the code, but perform any pre/post build steps that may fail the build (i.e. stylecop rules, tests, etc). This lets the user know right away if they have a bad build (if they haven’t run the correct build steps before committing), and gives you confidence that the build, at a fundamental level, passes the initial test.

7 Tips for Project Contributors

In this wonderful world of Open Source, not all of the responsibility falls in the laps of the project maintainers. For projects to flourish, it requires volunteers to take the first leap of faith and open themselves to contributing. This is a scary prospect for a lot of people, as they are afraid of being criticized or publicly ridiculed. I’m ashamed to admit (as a member of the OSS community) that this does occasionally happen, but cases are becoming more rare and, when they do happen, the community is quick to act and rebalance itself. Bearing in mind that the community as a whole will appreciate your contributions, here are some good tips to help get you more involved:

#1 Doesn’t matter what you are doing, get it out there and make it open:

As developers, we usually have code snippets and libraries that we reference and come back to tucked away on our local machines. As a first step, feel free to create a GitHub repository and make these public.

In reality, it almost certainly doesn’t matter what your fears are regarding your IP, as it’s highly unlikely that someone would steal your code. And even if they do, it’s unlikely that a snippet or helper class you have is going to make them (and not you) a million dollars. What you are much more likely to get is someone thanking you for making their job a little easier if your code helps them out. And you will also have taken your first steps to making your code public – congrats!

#2 If you don’t want to put code out there, contribute to documentation:

Open source projects are renowned for not having the best documentation. You can help change this by updating documentation, sharing your experiences and knowledge (as you gain it) for everyone to benefit from. Most documentation for projects is now in a repository that you can access and submit updates to. If you’ve taken the time to improve someone’s documentation, then once again – congrats! (and thank you!)

#3 Go and find two or three bugs in a project you know:

This can be a great way to get started, as there are almost always bugs that need fixing. Set yourself a goal to fix these in your lunch hour, and give yourself two to three weeks to do so. Even if you only do this once, you will become a better developer for it, and learn new practices in the process.

#4 Its not about the code, its about the conversation:

If diving in with bug fixing leaves you with an urge to do more, it also will leave you with the need to discover the protocols that a given project has (i.e. how Pull Request are handled, etc), so it’s usually a good idea to chat to previous contributors. Tell someone “I want to do X, and here is how I’m going about it. Do you have any ideas of feedback?”. If you’re new to a project, you will probably get the best response if the feature is small to start with, and you can move onto bigger items as time goes on and your confidence grows.

#5 Contribute to more than one project:

Getting to the point that you feel comfortable enough to contribute just within one project usually take some time and effort. If you haven’t done this before, the thought of doing it for more than one project could be fairly daunting. However, bear in mind that the more code and the more people you interact with, the more practices and architecture you will observe, and this will only make you a better developer.

#6 Don’t be afraid, most projects are open to any help they can get:

I’ve listed a number of different ways you can get involved in projects. Yet for all that, I know that even with all this information, and with project maintainers making it as easy as possible for people to contribute, most potential-volunteers are still anxious about putting their code (and by a mis-apprehended proxy, themselves) in the public arena. To this I can only say: if this applies to you, start small and find something that you feel comfortable with. You will usually be amazed at how receptive the community is to your efforts.

#7 Submitting 1 fix to 1 Open Source project puts you in the top 1% of developers:

Most developers never even consider taking the time to contribute to an open source project. By taking that step and committing to a project, you are opening yourself to new experiences and opportunities. Grab this with both hands and take if for a spin – it’s the only way you’ll learn if you like it!

This isn’t an exhaustive list of suggestions, but hopefully it helps make your project easier for people to come to, or gives you the confidence you need to approach a new project and start committing. If you’ve got any questions or suggestions, let me know in the comments or on twitter!

1 Comment

 Add your comment
  1. Sage advice Anthony. If more OSS projects would adopt this advice, there would be much more success. Thanks for posting this.

Leave a Comment

Your email address will not be published.

1 Trackback

  1. The Morning Brew - Chris Alcock » The Morning Brew #1357 (Pingback)