Cover image for How to be an awesome open source maintainer?

How to be an awesome open source maintainer?

aspittel profile image Ali Spittel ・1 min read

So, I open source pretty much all the personal code I write, but I've never looked for contributors for my projects before.

I decided that, since I have a lot on my plate right now, opening up Learn Code from Us to contributors seemed like a good idea.

But then I realized -- I have no idea how to be a good open source maintainer!

So, what are your tips for being an awesome one?

Also, if you would like to contribute here is the repo, there are a few issues open and most are beginner friendly!

GitHub logo aspittel / learn-code-from-us

People from underrepresented groups in tech who create awesome programming resources

Learn Code from Us

Project Introduction

The following text was taken from the about page on https://learncodefrom.us:

Learn Code from Us is a site that lists people who are members of underrepresented groups in tech who create resources geared towards programmers of all levels. These resources include (but are not limited to) podcasts, blog posts, newsletters, or YouTube videos. For now, this site is geared towards free resources in order to be as accessible as possible

Here is a blog post with more about the project.


If you would like to contribute, please add an issue or comment on one of the ones that are open that you are working on it. Then submit a pull request!

If you would like to discuss the project in more detail here is an open thread where you can ask code questions or discuss the future of the project!

Adding New



markdown guide

I have bookmarked this to get the answers myself!!

One thought: It’s a marathon not a sprint. If things are a slog or overly hectic now, don’t be discouraged, imagine how great this project will be if you stick to it for ten years!


I love that philosophy -- really smart to be future focused.


Yeah, but also self-forgiving in this way. I find it's easy to see all the things you wish you were better at as a maintainer and getting down on yourself, but I think it's natural to have weak spots, but you can fix them over time.

Taking all the suggestions in this thread and elsewhere, you can gradually improve your process, your ability to provide guidance, triage issues, maintain your sanity, know the project's true purpose, etc. But it takes time, and the important part is to just make the gradual improvements.

PS just created an issue, would love to help out with LCFU via brainstorm sometime too. πŸ™‚

I 10000% agree on being self-forgiving. Recently I've just been straight up honest with people saying I don't know (using the below meme a lot) and people almost always understand.

I have no idea what I'm doing

I forget this all the time but I feel better when I remember thatwe all want to help each other, and it's ok to be vulnerable, even as a maintainer. That always helps me forgive myself and get on with life :)


Based on my negative experience as a contributor, here's what I'd say:

  • You must have a chatting platform (Slack/Gitter/anything) set up in advance. I hate it when maintainers only provide their email or expect all the conversations to happen on issue threads.
  • Always have a contributing guide.
  • Never let your contributing guide read "Just send a pull request!" (drives me mad!). And to be honest, I can't believe people send pull requests all the time without discussing with the maintainer first, and then they are salty when those requests aren't merged. Ego?
  • Be (very) descriptive and encouraging in your Contributing guide. Tell people that it's okay if they don't have much experience, and that you're willing to mentor them. Means a LOT to a potential contributor.
  • Have a clear plan on what you're going to do next. I absolutely loathe it when people ask for contributors to "play around and provide feedback". Really? Why? I have better things to do with my time than provide feedback on random personal projects on GitHub.
  • And like the others said, create some simple issues on your own first, provide some details, and tag them so that newcomers can build confidence.

Hope this helps in creating one less shitty maintainer! πŸ™

(I'm sorry for spitting venom, but I'm extremely frustrated with how little attention maintainers give to presenting their own projects and then expect others to pitch in with their time and energies. 😑 😑)


And to be honest, I can't believe people send pull requests all the time without discussing with the maintainer first, and then they are salty when those requests aren't merged.Β 

Personnaly, I always create an issue to know if the community/maintainers are agree before I start to make changes.


Cool, will definitely try to implement these! It's a small project from a code perspective -- does a group still make sense?

Thank you so much!


If it's a really small project and new contributors understand exactly what needs to be done, you won't need a chat. But still, having a dedicated live forum helps one feel that they belong to a community and can chat with them when needed. For instance, if someone needs to discuss the approach (no matter how small the task), GitHub may not be the best place to do it. Maybe you can create a group for all of your projects, if all of them are small. I'm thinking of a Slack team with different channels for each project.

I guess, finally, you're better off consulting the contributors. Don't take anything for granted. What's crystal-clear to you may not be to them. πŸ™ƒ


Hello Ali,
Very nice work and repository. I have been working on my projects for few months now. But, this Hacktoberfest I started getting contributions from other developers using hacktoberfest label on issues.

What I have learned is that you will have to keep 3 things in mind and try to manage those as much as you can:

  1. Create a great Read Me and easy to follow instructions of what this is and how can you help.
  2. Create issues describing almost everything. Do not put just title. Put the issue description of like "What's current state?" and "What's the expected state?" and "How this should be done?". Describe it as much as you can and then I hope you will get good pull requests.
  3. Remain as much responsive as you can. Open source is global phenomena, so you never know what kind of timezone you get contributors from. So, try to answer their queries as fast as possible. That way, they won't lose you and they will work on it.

Hope this helps. Also, I am following this thread so that I can learn from other devs about their way :)

Good luck :)


Don't forget the CONTRIBUTING.MD it's a lot easier with this ^


Thank you so much! I especially like the part about issues -- going to need to put some work into them!


Your repo looks great so far and your response time on the issue I brought up was great, but there are two things I wanted to mention.

"help wanted" is typically used to get info back from the issue OP when not enough info is given, not as an alternative to "good first issue" (ps: if that's what you'd like to use it for, you can also change the description)

the hacktoberfest tag would fit more as a repo topic than as a issue tag


Awesome feedback, thank you so much! I will definitely change the tagging system!


I started a project a little while back and I'm totally pumped about it. I burn myself out pretty much weekly because I try to do everything.

I had a pretty stark learning experience that involved my health and me learning that I should step back way more often and let the community do its thing.

I wrote about it, and I hope it helps some other folks who feel like they're doing too much too!



On this website are some guidelines for

  • Starting an open source project
  • Building welcoming communities
  • Best practices for maintainers
  • Leadership and governance
  • etc


Also pushing for those best practices is probably worthwhile:

CII Best Practices Badge Program : bestpractices.coreinfrastructure.o...


This looks great.
I suggest trying the community-kit from the GH learning lab which can guide you on how to make a welcoming repo.
That pushed me into tailoring a template one (just for JS but it can be converted to other languages) which can be found here: github.com/Berkmann18/TemplateJS.

This alongside tools like Codacy, TravisCI, Better Code Hub (BCH) and what I learnt from going through the GH learning thing made all my more recent repos more informative and clearer (although, almost all of them are still solo so feel free to criticise them).


A few things that I've learned over the last year or so:


Have some kind of markdown file with instructions for contributors. Should folks who want to contribute create an issue before sending a PR? Should contributors work in their forked version of Master?

Some information on the contributors markdown file can be found here

Code of Conduct

Unfortunately, this has become a requirement of late. Need I mention Linus' track records of being offensive towards contributors to the Linux kernel?

(regardless of how you feel about his reactions, a code of conduct is always a good idea).

Do you expect certain behaviours from your contributors? By having a code of conduct, you are explicitly telling contributors how you want them to behave and conduct themselves whilst contributing to your repo.


When logging issues (even on my own repos), I try to be as descriptive about the issue as possible. Here's an example of one of my issues for OwaspHeaders.Core:

Feature-Policy header is not supported #31

GaProgMan avatar
GaProgMan commented on Jul 25, 2018


The OwaspHeaders.Core middleware does not yet include support for Feature-Policy which is a header related to enabling or disabling certain JavaScript API features.

Quote from Scott Helme's blog:

TheFeature Policy is being created to allow site owners to enable and disable certain web platform features on their own pages and those they embed. Being able to restrict the features your site can use is really nice but being able to restrict features that sites you embed can use is an even better protection to have.

Source: A new security header: Feature Policy

Links to Header Information

It's not the best example of an issue, but it's one of my most detailed ones.

The idea is that you want to give potential contributors the most information that you can, in order to get them up to speed with the issue as quickly as possible.

Where possible I try to include a pseudo-code version or 10k ft view of a possible solution, and include links to lines in the code base where the solution could be implemented, too.


Thank you so much! I added the COC and Contributor guide to the issues -- both are so important, and should definitely be addressed ASAP.

Great advice on issues too -- thank you!


Yes! Definitely going to add that, and maybe add some additional language with positive actions in addition to negative.


Not a problem.

Like all of us, I'm still trying to figure out how to be a great open source contributor and maintainer.


Some pretty good advice here. Couple of other (and perhaps contradictory advice).

  • Get CI up as soon as you can and working for all branches. This goes a long way towards knowing if that PR is legit or not.

  • Make sure that you have detailed instructions on how to run the test suite and that they all pass. It is infuriating to pull down a repo, run the tests and find a bunch that fail -- if only because now I don't know whether my changes are going to make it worse or not. The more complicated the project the more details the instructions need to be. Call out specific version requirements if necessary, etc.

  • If you've got a style guide, get that into CI and the contribution guidelines as well. Tell me what tools I need to make it work too so I don't have to try and guess what tool that .randomstyleconfigdotfile wants to use. Tell me what version. Rubocop in particular can vary dramatically from version to version.

  • Unless you are popular and have a team of folks that can help, I wouldn't advocate a live chat. You have zero control over when you'll be interrupted. You're not being paid for this. I feel as the maintainer you have the right to take some time for yourself and address issues when you can. Obviously this is a double edged sword. Ignore them for too long and you're gonna lose people, but people who expect me to respond to their issue in <1 hour are gonna be unhappy.

  • Have a Roadmap. This will give people an idea of where you want to go -- and more importantly where you aren't willing to go so they don't waste time writing up a PR you have no intention of merging.

  • Remember that it is okay to say no to PRs. You are the visionary and guide.

  • Thank people for submitting PRs. They are doing this for free too.


The Changelog Podcast had an episode related to open source maintenance last week : changelog.com/podcast/318 . Might be worth a listen if you've got some time :-)


Hi, your repo is not as intimidating as other i tried to start with. I will look at your issues to see if i can help, i want to start colaborating open source :) thank you sharing :)