loading...
Cover image for 10 tips for maintaining an open source project

10 tips for maintaining an open source project

compscilauren profile image Lauren Stephenson ・10 min read

Cover Image by Tumisu from Pixabay

Becoming an open source project maintainer is as easy as creating a public repository on GitHub, or on any other open source hosting services.

But what can you do to make sure you're being a good maintainer?

If you're familiar with contributing to open source, you probably have an idea of what a beginner-friendly repository looks like.

A lot of these tips are things that benefit new project contributors, but all of them are things that improve the experience for everyone.

Here are a few things that I've learned, both as a maintainer and as someone looking to contribute to other projects.

1. Choose a license

This is easy to overlook. You might think, who cares? My project is small, and I don't care what people do with my code.

Well, a license doesn't just protect you or your project.

It gives people confidence in using and/or contributing to your project.

I've seen people online say that if your project doesn't have a license, they won't contribute to it or use your code in any of their work.

If the rules aren't clear, why risk getting involved?

Visit choosealicense.com to quickly and easily find out which license suits your project best. Having a license is a best practice. Don't skip this step!

2. Add documentation

Screenshot showing list of common community-based documentation

This is absolutely critical if you want anyone to contribute to your project.

Nobody is going to bother with your project if you don't even have a README.

Think about it. When you look at other people's projects, what's the first thing you look for? You look for written information, right? Anything that tells you what you're looking at, what it's for, how to use it.

Make it easy for people to find the information they want. A good README goes a really long way.

Whenever I need some inspiration, I scroll through the Awesome README repo. Definitely check it out for some fantastic content and layout ideas.

Finally, go to your GitHub repo, click on the "Insights" tab, and click on the "Community" tab.

This shows a list of common documentation you should have. The more of these things that you have, the friendlier your project will appear to potential contributors.

Including these pieces will make it easier for people to start contributing. It will also lay out the ground rules to help you maintain a productive and positive community. Nobody wants to be in a toxic environment.

3. Create Issues for each task and label them

Screenshot of a GitHub Issues page on a GitHub repository

Create the Issue

When you know of a bug or feature that needs to be worked on, make a GitHub Issue for it. Encourage others to create Issues as needed.

If you followed step 2, you should have Issue templates for people to use. These are helpful for you as well!

Fill out the Issue with enough information so that someone could look at it and know if it's something they'd be interested in taking on.

Add labels

Don't forget to add labels to your Issues. These can provide a lot of information at a quick glance.

Is this Issue beginner-friendly? Is it being worked on by anyone yet? Is it a bug or is it a new feature?

Help people find the answers to these questions quickly by using labels.

4. Share on social media and any relevant websites

A person logging into Facebook on their phone and looking at a generic website on their laptop

Image by William Iven from Pixabay

Social media is a fantastic place to learn from different perspectives, meet other coders, and share your project with potential users.

Look for places that would be relevant to share your project, and follow their posting guidelines. Try not to post it so often or in such a way that it comes off as spam.

You could tweet about your project, post it in various communities on Reddit, even share it on Instagram. You can bring it up in comments wherever it's relevant.

You can also change up the reason behind posting. You can share it just to let people know about the project. You can also mention it but with the focus of asking for advice or feedback about a particular aspect of it. If there's a new update that's just been released, you can post about that too.

You might just make posts about it from a personal account. You can also consider creating an account specifically for the project.

If you opt for that second option, then when you make a post it will appear to come from the official account rather than the creator of it. This can be more enticing for users to follow, but it really just depends on the situation.

If you're looking for users specifically, see if there's a website dedicated to the kind of thing your project is about.

For example if you make mods for a video game, there's probably a website where you can upload your mod. You can also create your own website to showcase the project. Again it just depends on the situation.

5. Make the most out of Hacktoberfest

Hacktoberfest 2019 t-shirt

Image from Recapping Hacktoberfest

Hacktoberfest is the best opportunity of the year to attract new contributors to your project.

Everyone will be out searching for projects they can contribute to, and a project with a lower barrier to entry is bound to gain some attention.

If you want to make the most of this month-long spike of contributions, make sure you've followed the previous (and following) steps.

This is an especially great time to be a little more active on social media. Share your project on relevant posts, and make your own posts too.

If you come across a list of beginner-friendly projects and yours is indeed friendly, see if you can get yours added to the list.

If you do start getting comments anywhere or contributions (yay!), make sure you're friendly in your interactions.

If you get a contribution from someone but you'd like to request or make a change, that's totally fine. There's nothing wrong with politely letting them know that you have some requested changes.

Remember, this is an event that attracts lots of beginner contributors. We want them to feel welcome! Don't make anyone feel bad for not knowing something or if you need them to modify part of their contribution. Be patient and kind, as you hopefully are even when it isn't Hacktoberfest.

6. Assume good intent until clearly shown otherwise

It might surprise you, but this is an easy one to mess up on.

One of my first contributions got a comment on it saying that the text on a README file was too wordy. I figured that was fine, I can make it more concise. I updated the file.

Someone else commented and said that the file was "quite verbose".

Quite verbose? Are you serious?

That hurt. I was trying to contribute something that I had put a lot of thought into, and I didn't like the phrase "quite verbose". Especially right after I had already made the text shorter.

I was upset, and my response made it apparent to that person. Luckily for me, they responded kindly and we were able to work through it.

It was easy for me to get hung up on that phrase they used. But I should have assumed good intent.

Not everyone uses the same words to describe things. And what they said wasn't clearly intended to be toxic or hurtful. Plus, it was kind of true honestly.

It's tough! You put your heart into something, and then you have to let people critique it. That's how code and other contribution reviews work.

The best advice I have here, is just remember that reviews aren't an attack on your character or how good of a programmer or writer you are. It's simply a review of the contribution itself.

Everyone wants whatever is best. No contribution is absolutely perfect. So try to assume good intent unless it's clearly toxic language or behavior.

7. Ask a friend for feedback

Three friends sitting on a blanket in the grass and looking at something on a laptop together

Image by Sasin Tipchai from Pixabay

What's better than getting advice from Internet strangers? Getting advice from a trusted friend, of course!

Whether it's a question about your code, or your social media outreach, or which website layout looks best, don't forget you can always ask a friend for feedback.

If your friends aren't available to help with this kind of thing, you can try to connect with someone on social media.

Making friends on social media can be fun and really helpful. You'll be able to bounce ideas off each other, support each other, and ask each other for feedback.

If you're going to ask for feedback from someone directly on social media, remember to be considerate. If they say no thank you, be polite and don't continue asking them.

If you can't find a specific person who would be good to ask, remember you can always make a public post for anyone to comment on.

8. Show appreciation and share sense of ownership

Two people shaking hands but one of the hands is coming out of the digital screen of a laptop

Image by Gerd Altmann from Pixabay

Always be kind and remember to show appreciation to the people who help you, and to the users of your project.

Give contributors a sense of ownership. People care about the things they own.

I don't mean that you need to literally tell people that they "own" the project. But don't make it feel like they're separated from the project either.

Don't look at it as "this is MY project, MY code, MY community". Think of it as a collaborative effort by everyone. You can just use that kind of phrasing when you speak. "WE did a good job, WE have an awesome community" and so on.

If you look at it as a community thing and not as a "this is all mine" kind of thing, it will show in the language you use. The language you use can make people feel a stronger sense of belonging, or it can make them feel distanced from the project.

9. Build with the user in mind

A collage showing lots of different people and phones along the middle horizontal area

Image by Gerd Altmann from Pixabay

Remember that at the end of the day, you want your open source project to be useful to other people.

Make sure it's easy enough for users to get started with your project. If you find users asking the same questions, address those frequently asked questions in the instructions or setup process.

Keep in mind what your users would like to see. If they offer you feedback, listen to them and consider the things they say.

Lastly, be sure to always act ethically and have their best interests at heart.

10. Take care of yourself

A cup of tea and a tea bag with a heart in the middle sitting on top of a journal

Image by Free-Photos from Pixabay

Really, truly, take care of yourself.

Contributing to open source can be hard, and maintaining an active open source project is typically even harder.

You'll often find open source projects with tons of open pull requests and Issues.

It can happen if a project is really popular, or if the maintainer becomes overwhelmed and slows down on how many Issues or pull requests they close.

Having a high number of these can get overwhelming really quickly, especially if you don't have much help.

Remember to take a breath. Do what you need to in order to be okay. Your well-being comes before the project.

It's definitely good to consider having a second person who can help actively maintain the project, if things start to get busy.

If you're in school or have a full-time job, it can be especially challenging to manage open source projects on top of it all.

Remember that you're awesome, it's good to take breaks when you feel stressed, and it's okay to ask for help when you need it.

Conclusion

With the right balance and support, maintaining an open source project can be an awesome experience.

I hope that by keeping the above tips in mind, you'll have even more success with your project.

Did I miss anything? Feel free to share your own tips below!

This article was originally published on my personal website's blog, Joy Bytes.

Posted on by:

compscilauren profile

Lauren Stephenson

@compscilauren

Software Engineer. First gen computer science major, graduating Dec 2020. Stardew Valley Modder. Sleep Enthusiast. Plant parent. JavaScript, React, UI/UX Design, Open Source. she/her

Discussion

markdown guide