DEV Community

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

How to be an awesome open source maintainer?

Ali Spittel on October 19, 2018

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 ...
Collapse
 
ben profile image
Ben Halpern

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!

Collapse
 
aspittel profile image
Ali Spittel

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

Collapse
 
ben profile image
Ben Halpern

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. 🙂

Thread Thread
 
arschles profile image
Aaron Schlesinger

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 :)

Collapse
 
wajahatkarim profile image
Wajahat Karim 🇵🇰

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 :)

Collapse
 
dimensi0n profile image
Erwan ROUSSEL

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

Collapse
 
aspittel profile image
Ali Spittel

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

Collapse
 
nektro profile image
Meghan (she/her) • Edited

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.

image
"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)

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

Collapse
 
aspittel profile image
Ali Spittel

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

Collapse
 
dimensi0n profile image
Erwan ROUSSEL

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.

Collapse
 
janux_de profile image
Jan Mewes • Edited

On this website are some guidelines for

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

opensource.guide/

Also pushing for those best practices is probably worthwhile:

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

Collapse
 
arschles profile image
Aaron Schlesinger

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!

medium.com/that-conference/on-step...

Collapse
 
berkmann18 profile image
Maximilian Berkmann

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).

Collapse
 
dotnetcoreblog profile image
Jamie

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

Contributors

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.

Issues

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

Description

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.

Collapse
 
aspittel profile image
Ali Spittel

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!

Collapse
 
weswedding profile image
Weston Wedding

I'd suggest checking out Contributor Covenant

contributor-covenant.org/

Thread Thread
 
aspittel profile image
Ali Spittel

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

Collapse
 
dotnetcoreblog profile image
Jamie

Not a problem.

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

Collapse
 
phallstrom profile image
Philip Hallstrom

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.

Collapse
 
aspittel profile image
Ali Spittel

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!

Collapse
 
diek profile image
diek

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 :)

Collapse
 
ohffs profile image
ohffs

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 :-)