This document serves as a way for this project's maintainers to document their process of getting their repository ready for the 2020 Hacktoberfest alongside the Virtual Coffee Hacktoberfest Initiative. We also hope this project continues beyond just Hacktoberfest, and so we thought it best to collect all the knowledge, resources and learnings we pick up along the way in one central place, both for our own reflection, as well as sometimes that others can use to create welcoming and valuable spaces for their own open source contributions.
While we will try as best as possible to create a body of knowledge that is accessible and understandable to everyone who finds it, we hope you understand that this may not always be as comprehensive, current or exact as you may want to be. The language will be more candid that you might find in your typical technical documentation, and YMMV (Your mileage may vary) will almost certainly come in to play. There may be some aspects of this template that you do not agree with at all, and that's okay. We're not about dogma here, just about good intent and prioritising empathy and communication over absolutisms.
Ultimately, this project is simply a labour of love by folks who love coding, and community, and want to give back some of what they've received.
We hope it helps, and encourages you to try your best.
- Introduction
- Synopsis
- Expanded Resources
- Why Become A Project Maintainer
- Getting Started
- Using Github Community
- Using Github Projects
- Using a Wiki
- How to Communicate Effectively
- Using Tags
- Being Sustainable
- Advanced Topics
- Additional Resources
We realise that time is a commodity and someone might not want to read this entire document so we tried our best to condense the gist of the advice into the following five bullet points. Essentially, if you want a good start on being a good maintainer:
- Get your community docs in order (readme, contributing, code of conduct, license, etc)
- Use public tools to describe what the project is and what its goals are.
- Use templates wherever possible to guide people (yourself included) to submit good work.
- Be clear in the style of communication you like, and your response times.
- Moderate your project space for bad actors.
- Pace yourself and plan for the future. Don't burn out on something you're not being compensated for.
- PLEASE tell your users how to build your app
The internet is a big place. In the course of writing this guide in preparation for hacktoberfest we stumbled upon https://opensource.guide which has more resources than we could ever hope to compile. It would be nice if you read our short wiki of resources but we absolutely recommend you check out that space as well. It seems like a real labour of love and it covers every OSS topic under the sun.
A lot of people think that being a open source project maintainer is the same as being a project creater, except you have to review pull requests that aren't your own. This is not true.
Just because your code is available on GitHub, that doesn't mean you've facilitated a space where people can make contributions.
Good reasons for becoming a maintainer are the following:
- You want help on a particular application
- You have big ideas but they would take too long to come to fruition on your own
- You want to practice project/team management
- You want development of your project to take place even when you cannot work on it
- You want to have fun with others
- You want to mentor and teach new developers
- You want your project to thrive
Choosing to be a maintainer means that you're attempting to be more than just a code jockey bashing keys and hastily debugging, but rather, becoming a steward who is invested in creating a quality developer experience, both for yourself, and the others who choose to interact with you.
Choosing to be a maintainer means that you've resolved yourself to the idea that this project would be better served by the contributions of others rather than just you, and you can put your ego at the door.
It means that you actually make the effort to help people help you and provide the smoothest possible experience to get the quality assistance that you desire.
Being a good maintainer means expressing, though your repo environment, your communication, and your demeanour, the concept of "Hey, I think this thing I'm doing is cool, and I want to share that with other people", as best as you can.
Pathos aside, successful coordination of an open source repo is a great way to practice skills that are valuable for anyone in the software development space. It is 100% a good look to be competent manager of an open source project and it's a sign of a mature and competent software architect/project manager.
It's also a great way to mentor junior developers looking for knowledge and experience And that process of teaching can then sharpen your own development skills.
In a certain way, OSS work can be even more challenging than work in established organisations, because unlike employees, contributors have no external incentive to work with you other than because they want to. Getting people who aren't being made to act in a coordinated fashion is always challenging, especially when you have a short window of available time to do it. It's not impossible, but it does require some effort and it's perfectly okay to not do it if it will put a strain on your health/relationships.
That being said, if you think you have the time and energy to do it, but are merely trepidatious, the resources below should help alleviate those fears somewhat. Or at the very least, give you more context as to whether or not you can do it.
If any of that sounds good to you, read on.
Please be aware that you absolutely do not have to do everything we've noted below before you can start working with others on an open source project. As best as we can, we've tried to order these resources by what we consider (in our very very subjective opinions) to be the the most important documentation first, as well as the order in which we present resources. Where we feel certain aspects deserve higher priority and attention from others, we try to say so. Please let the maintainers know if you encounter any problems in reading, understanding, or following the information provided below.
If you plan on doing multiple OSS projects, We highly suggest creating all of your efforts in a repository template. That way, you only have to do this setup work once and ever time after that, you can simply start your projects off with this template, and have everything ready to do! This associated repo to this project is in and of itself, a repository template. Practicing what we preach!
The first thing we need to establish with this Open Source Maintainer stuff is that, you don't have to figure this all out yourself. In the process of getting this project ready we discovered a ton of resources already baked in the the GitHub platform to help you be a better developer. Foremost among them is GitHub Community. Honestly, Github has done a fantastic job of putting this together and it addresses more than we could ever cover by ourselves. The document pulls a significant amount of resources from Github's document of being good repo communities and while the info does focus a lot of the Github platform and API, the concepts are applicable on any public repository platform. They've truly got the experience thought out from top to bottom and it's a must read for anyone planning to host their own application.
Every good open source repository starts with a good README. Out of every single file in your repo, the README is the one that 99% of viewers (and potential contributors will interact with first, and you can basically treat it like the front page of your application. If there's a single thing to do that can bring the best bang for your buck in terms of getting and keeping contributors, it's making a well crafted README. Many projects choose to forgo keeping separate community documents entirely and just keep all the project info in the README, which if organised well enough, can also be perfectly effective.
Lucky for you, many people have recognised this so there's a variety of resources out there for you to work with.
Make A Readme is a great site for getting a great breakdown of what a good readme entails. Key sections to include are
- What is your project about
- HOW TO GET THE APPLICATION WORKING
- How to people find the other community pages (see below)
- Contact information
- Version and License Info
Matias Singers has an awesome readme that has examples of great readmes which you can look at for inspiration.
Just remember that a readme is a living document that you should try and keep current to the state of your application. Always try to stick to relevant fields to avoid clutter, and dont be afraid to use images and colours to make your README more engaging. It's your project's 'face' after all. Nothing turns away folks faster than an empty README, because it makes people think "this project isn't ready/wanting outside assistance, this person has just put their code up here."
The value of a contributing doc is based on three central ideas:
- People can't help you if they don't know how.
- People can't do things the way you want if you don't show them how
- For a would-be contributor, reading a document is much less trepidatious than sending an email.
Providing an accessible way for people to know how to submit to your project can avoid hours to weeks of back and forth with contributors, and is a great way to keep from having to repeat yourself when people submit issues or pull requests that aren't up to scratch.
Github's short article Setting Guidelines for Repository Contributors walks you through the steps of creating a CONTRIBUTING.md file in your repo which GitHub will highlight for new developers.
If you want to work with people, you have to be clear on the types of behaviours and norms you consider acceptable in your spaces. Open Source means public to view, but it does not mean lawless, and it definitely does not mean freedom from consequence. The code of conduct is also a great way to let the people who you do want to make sure feel welcome and included know they have a safe space to engage in. No one enjoys contributing to a project where they fear persecution and derision and a public declaration of intent for equality can go a long way.
A code of conduct also lets people know up front who you are, your values in the spaces you reside in, and what you expect from them if you choice to let them enter that space. That means that there may be times when people do not engage with your project due to this, and that's fine. That just means that you've both avoiding the time wasting that would've resulted from them trying to work with you and clashing with your ideals.
Many people stand by the Contributor Covenant Code of Conduct which is available for public use and can be posted in any repository. If there's anything you wish to say but you feel isn't covered in the template, you can always add it.
This repository uses this template from the Geek Feminism wiki.
Note that you can always do a COC from scratch. Effort counts.
The support file was actually a very recent discovery of hours but we love the idea. A dedicated document for telling people the best ways to get help with your project or application. A lot of people find repos because they're trying to troubleshoot an application and letting them know the best way to find a response/answer can definitely reduce stress an agitation. It can be a good way to provide people the tools to solve their own problems (and yours as well), by offering up valuable advice for troubleshooting, debugging, and providing fixes.
Obligatory Github article about support files because it's great.
At the end of day, after you've done all this prep work, moving your project forward in a sustainable way is going to involve the creation of Issues and Pull Requests, both by yourself and your contributors.
There lots of great resources on writing good issues like this article by Andy Cochran and on writing good pull requests (see this article by Sajal Sharma) and its perfectly fine to create articles like this on your contributing.md file, or link to them.
By recently, GitHub has introduced the ability to make persistent templates which help you provide your contributors with a working guide to follow for submitting issues and requests. Once again, this is a great way to front load the work of explaining what a good issue/PR is, and saves you a ton of time down the line because your template do the job of informing people how you'd like work to be introduced. Github will walk you through the process of creating these and adding them to your application.
An open source license protects contributors and users. Businesses and savvy developers won’t touch a project without this protection.
Licensing adds a touch of professionalism to any software application and sends a strong signal that you've put thought into what the project is and the purposes it serves. However, actually choosing a license can feel daunting because there's quite the plethora of options out there nowadays and it takes a lot of time and energy to read through each and every one to find the thing most perfect for your application. So unless you're into that sort've thing, we highly recommend (and Github does to!) using a site like choosealicence.com. The completely streamline the process by asking you the end result that you desire from your license in terms of protections and present you with the license that best suits your needs.
And remember, if the license you want is part of Github's curated list, the Github interference allows you to simple select the license you want and it will make the license.md for you
Yay automation!
That covers the key things we wanted to highlight from the GitHub Community initiative. There are a few extra steps which can be navigated to from the links about but getting the aforementioned files in your repo (or consolidating the data the information they would provide in a README) is already far and beyond what most developers provides and will absolutely make your project stand out as being contributor friendly!
If you're trying to treat your OSS project more like a professional software project, a great way to start is the introduction of Github Projects. It's a quick and easy way to create a kanban board where you can track ideas, tasks, goals, and work progress as your application progresses.
Github currently let's you even do automation with your project boards so Issues and Pull Requests get automatically added as tasks to be accomplished. This is great for avoiding work duplication. It's also just a great place to dump thoughts and ideas that you want to use to plan later.
Okay, now this is getting way too meta. But seriously, a wiki is a great place to store project documentation and you literally get it for free with your repo. It's especially useful if your project has a public API that you want people to utilise. Good use cases for your wiki could be:
- Creating documentation for your APIs
- Posting technical details of your application you think are worth recording
- blog posts about various aspects of the work
- highlighting your development/product team
Wikis themselves are git repositories, so you also get a living history of the changes over time.
And of course, Obligatory Github article about using wikis.
Honestly, good communication could be its own 20 page treatise, but we're going to try our best to hit the salient points.
Remember what you want.
The goal is to get people to contribute quality work, in a harmonious fashion with the goals of your project.
A few fundamental points that have remained consistent throughout the entirety of the human experience:
- People who feel disrespected do not give you their best work
- People who feel belittled to not produce their best work
- People who feel ignored do not produce their best work
- People who feel harassed do not give their best work
The name of the game when it comes to OSS contributions is empathy and respect. No matter what, if someone is taking the time to try and help with a project, it's best to approach all dialogue from a position of appreciation for what they've done, rather than disdain for what you feel is lacking. A few other tips to consider:
-
Thank people immediately and publicly - Always thank people for their contributions. Submitted issues, PRs, even taking the time to ask a question. They didn't have to, and even if you can't give them. your full attention yet, people tend to be a lot more patient after receiving acknowledgement of their efforts.
-
Make your communication style clear - It's probably a good idea to include in your communication docs some statement about your preferred methods of communication, rough time lines for responses, etc. If you check the repo once a day, then maybe you can let people know to expect a response in 24 hrs or less. If you can only find time once a week, that's okay, but let people know that from the get go, so they're not stressing out over when and how you'll see their contributions.
-
If you go over your expected response times, apologise and move on - We're all adults here. A quick apology for tardiness is all you need and lets people know your original time commitment wasn't just a false promise.
-
If you consistent take more time to respond than you say you will in your docs, update those docs - I'd honestly prefer a maintainer who spoke once a month but I knew that's how they worked than a maintainer who says they'll check in every day and they never do. It's all just expectations.
-
Praise first, then critique - Whenever possible, highlight what you like about a contribution before you discuss flaws. Notice we said critique, not criticise. Don't complain at people. Just clarify what you're looking for, note the difference between that and what they provided, and ask if they can make adjustments.
-
FORMATTING FORMATTING FORMATTING - No one wants to read walls of text. And plain unsettled text is functional, but boring. At the end of the day Well articulated, concise explanations will beat out fancy styling every time but also, good styling never hurts. Use headers, spacers, line breaks, and other tools liberally. It's probably worth it to peruse the Github markdown guide to make your work as presentable as possible. Pretty much every aspect of writing on this platform uses markdown, so it doesn't hurt to know the basics.
-
Expect friction - No one is a mind reader. People will try to do their best but they can never know exactly what you want to do in your head. Be as detailed as possible in issues and docs describing exactly what you want. But use common sense. Spending ten minutes writing a good issue for a multi-hour long PR makes sense. Spending two days writing a good issue for a 5 minute PR does not (you could've just done the PR in that time). The whole purpose of this is to make your life easier remember.
-
Protect your integrity - You NEVER have to tolerate disrespect, attacks, or harassment from any contributor and do not hesitate to cut off engagement from anyone who you feel is violating your Code of Conduct. Github has some good resources on maintaining safety for yourself and your contributors
-
Remember that you're talking to another human being - It can be hard to practice empathy when all you see is a username and some text but remember that everyone here is just one human trying to do a thing. Being a maintainer is good space to practice patience and understanding, and a plan where you can ask for, and receive understanding as well.
After working on some issues and pull requests, we wanted to create a section here to highlight some of the tags we've been using in our project that have provided value to us. There's lots of good resources on tags, but we've found that discovering organically what tags provide value to your organization help as well. A key resource was this article by Dave Lunny. All credits to him for suggesting some great techniques.
Good Label types, in no particular order:
Type: {value}- This is great way to organise issues and PRs. Talks about the kind of issue being made. We generally use 4 types of issues,Documentation,Bug,Enhancement, andQuestion.Status: {value}- This is a great way to signify the stage of the process an issue or PR is it. An especially useful one for us isStatus: Assignedwhich lets people know an issue is being worked on by someone else.reserved for maintainers`reserved for new devs\rated E for everyone` - this set of tags is great for identifying setup who you want working on particular issues in your applicationNo coding required- really helpful for newbies who might be trepidatious about writing code. Also good for people who want to help but do not have experience in that particular tech stack.Repo Maintenance- for tracking issue that require modifying the repository space, as opposed to the application
Just to be clear, you should actually try to finish your projects. But life is uncertain, and sometimes it takes a bit more planning than trust trying really really hard to get your work to completion. A few things that can help make sure your efforts don't go to waste:
-
Plan project stages - Instead going for the long goal immediately, break your project into smaller milestones that last anywhere from a few weeks to a few months at a time. Closer goals are easier to psyche yourself up for and you get to celebrate those wins with collaborators which are also energised by achievements. Utilising sprints like a professional development project might not be a bad thing either.
-
Invite trusted contributors to greater roles of responsibility - Having people you trust handle some decisions so you don't have to put out every fire yourself is huge. If you are doing all the right things as a maintainer, you'll naturally draw amazing contributors and after some time to establish trust, you can reach out as if them if they'd like to do more. Github allows you to make official teams and collaborator spaces that facilitate this.
-
Take breaks. Plan project "vacations" - There's no reason why your Open Source project can't operate like a paid/traditional project, with scheduled time where you are not working on it. As long as you make it clear in your community docs, you should absolutely take time off projects, especially after long periods of work. Better a two month break than a feverish 2 years of effort then abandoning forever.
-
Allow forks - Make it easy for people to continue with your work if you're ever forced to stop. Collaboration is what open-source is all about.
In the interest of keeping this updated as we continue to gather new skills and techniques we've added some quick notes about things which are probably not necessary for getting your oss project going, but are skill useful tools for maintaining a successful project.
Continuous Integration and Continuous Development (commonly referred to as CI/CD) are an important part of any modern software endeavour
What Is Continuous Integration (CI)?
Continuous Integration is the practice of merging in small code changes frequently - rather than merging in a large change at the end of a development cycle. The goal is to build healthier software by developing and testing in smaller increments.
As continuous integration platform supports your development process by automatically building and testing code changes, providing immediate feedback on the success of the change. Travis CI can also automate other parts of your development process by managing deployments and notifications.
CI Builds and Automation: Building, Testing, Deploying
When you run a build, your CI platform clones your GitHub repository into a brand-new virtual environment, and carries out a series of tasks to build and test your code. If one or more of those tasks fail, the build is considered broken. If none of the tasks fail, the build is considered passed and your code can be deployed to a web server or application host.
CI builds can also automate other parts of your delivery workflow. This means you can have jobs depend on each other with Build Stages, set up notifications, prepare deployments after builds and many other tasks.
If you're using Github, you can set up an integration with Travis CI, a well know CI platform. At the time of writing thing, Travis-CI offers a FREE TIER of service if you're working on an open source project. You should definitely not pass this up.
One fun way of spicing up your project readme is with badges also known as shields. You've probably seen these on some READMEs on the site and they can cover a lot of territory, from providing live development information about your project, to just being a cool method of personalisation. https://shields.io has hundreds of pre-existing shields as well as allows you to create your own!
The more we learn about GitHub, the more it continues to impress. Github apparently allows you to create automatic responses for certain actions that happen in your repo, like sending a message whenever someone commits to your repo for the first time. See more details here.
Hopefully this document helps someone in growing their project community. We will keep updating the resources and style of this and try to keep from getting too outdating.
If you took the time to read it all, thank you. It you think there's anything we can add, or improve upon, please feel free to send us an issue!
- A guide to great commits by Vic Vijayakumar!
- Matthew Rocklin's article on How to be a good maintainer
- A guide to making good comments on Issues and PRs
- Steven Mao's repo of issue templates
- Writing a Proper Github Issue by Andy Cochran
- How to write issues by Quentin Berder
- Creating Table of Contents Manually with Github flavoured markdown by Hillary Fraley
- Radical Candor for Code Review by Rina Artstain
- Making Colourful badges for your readme
- This Repo for getting started in open source