loading...

Don't be a meanie when contributing to open source

derekjhopper profile image Derek Hopper ・3 min read

In 2019, I replied to a post here on DEV about contributing to open source. After a year (and 10 years of COVID), it feels like a good time to share those tips again and expand on what I wrote.

Give thanks

Whether you're reporting an issue or opening a pull request, thank the author(s) for their work. To me, this becomes especially important if you're using their code in one of your projects.

This is a great time to thank them for making your life easier. Use this as a chance to start off on the right foot.

Read their contribution guidelines

Many projects these days have a few places to help you get started.

First, look for a file named CONTRIBUTING.md and read it. Often, this file will include information on how to report issues, open pull requests, and other ways you may be able to contribute.

Second, watch out for CODE_OF_CONDUCT.md and read it carefully. Think of this file as a primer before you communicate to anyone on the project. Be mindful and stay within the rules of the project.

Lastly, use DEV as an example. Here's the CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Unsure? Open an issue and discuss it

If the CONTRIBUTING.md file doesn't explain what the project is open to accepting, use an issue to propose your change. Politely ask the project if it's something they'd be interested.

This can apply to bug fixes and is gravely important for new features. If you don't want to be disappointed, don't spend time working on a feature the project may not be interested in accepting. Some projects simply don't accept new features anymore.

Find a bug? Provide a failing test case

The best way to communicate a bug is to either provide a failing test case or the steps to reproduce it.

If you know the language the project is written in, fork the repository and write a test proving the bug you're reporting. Give a link to your fork when opening the issue.

If you don't know the language or you're unsure of how to write the test, try to give as much information as possible. Explain how to reproduce it. This is a good time to check the CONTRIBUTING.md file where they may have a template for reporting issues.

Make yourself available

Once you open an issue or pull request, don't go radio silent. Be ready to respond in a timely manner if the maintainers have questions.

Your work is much more likely to be accepted if you're willing to work with the maintainers to make it so. Maintaining an open source project is a time consuming endeavor. Anytime you can save the maintainers is a job well done.

Follow the conventions

This is a guideline you can use anywhere where software is developed. Try to stay within the conventions of the project.

If the project uses four spaces for indentation, use four spaces - not two. If the project uses tabs instead of spaces, use spaces - just kidding, use tabs.

This even goes as far as how tests are written. Try to follow the patterns laid out by the project. This increases the likelihood of your code being merged.

Explain as much as possible

Once you've worked hard to finish a pull request, try to be a good writer and explainer. Share why you did things a certain way. If you're unsure of a particular section, point that out.

Your goal should be to make it easy on the maintainers of the project. Don't be afraid to point out rough sections of the code or parts that may not make sense to the next person that reads it.

Imagine the maintainer knows nothing about what you did.

Be nice

Finally, nobody is going to get mad at you for being nice. Someone that's easy to work with is usually better than someone that's not.

It's common for open source maintainers to do their work in the moonlight. Be a pal and avoid getting frustrated if things take longer than you think they should. Ask if there's anything you can do to help the process along.

What about you?

Do you have any examples of issues you've reported or pull requests you've opened and you followed some of these guidelines?

Posted on by:

derekjhopper profile

Derek Hopper

@derekjhopper

Golfer, gamer, full stack web developer.

Discussion

markdown guide
 

I'll start. Here's a contribution I made in 2016..

  • I forgot to thank the author of the project.
  • I tried to explain the change as best I could. I'm not a Python developer, but knew the language enough to open a small pull request.
  • I tried to follow the conventions as best I could. This particular project didn't have extensive testing, so I wasn't sure how to add a new one.
  • I pointed out one area I thought was a little odd. That way the author could see it and give advice.