1. Be Respectful and Kind
Maintaining a repository can be a frustrating affair — especially when it’s a popular repository and you’re volunteering your free time to an open source project and you’re about to answer the same question for the hundredth time. It’s understandable that you may be very curt to the next person who asks the same question. It’s a waste of your time, and they didn’t do their due diligence to search to see whether the question was already answered.
Resist the temptation to lash out. For that person, it may be the first time they’ve ever created an issue. They may not have read this chapter yet and learned how to be effective on GitHub. Your response will set the tone for their experience of your project and, perhaps, of GitHub as a whole.
Be respectful and kind, and you may win over someone who will become a lifelong contributor. And even in the face of rudeness, remember that we all have bad days. You’ve probably done the same in the past yourself. The Internet can be very impersonal when communicating in writing. Sometimes a little kindness at the right moment reminds people that a human is on the other side and there’s no need to be rude.
But to be clear, killing them with kindness is fine for the occasional rude behavior, but you should not have to tolerate abusive behavior.
2. Report Bad Behavior
Whether bad behavior is directed at you or others, it’s important to the health of a community that we remain vigilant and report it. If you encounter or witness abuse on GitHub, report it at https://github.com/contact/report-abuse.
It can be difficult to know the difference between someone just being slightly rude and someone being abusive. GitHub’s Terms of Service help spell it out. If you’re unsure, know that GitHub’s support people are well trained to draw this distinction and will not react in a knee-jerk fashion to your report.
Abuse isn’t the only type of issue you may want to report to GitHub. You can report harmful content, privacy concerns, and copyright claims from GitHub’s contact page at https://github.com/contact.
3. Write Good Bug Reports
For a repository maintainer, few things are more frustrating than an issue that looks something like this:
The thagomizer isn’t working, fix it! I tried it out, and it doesn’t work.
This example may seem extreme, but vague bug reports that are not actionable are unfortunately quite common. It doesn’t take too much effort to write a bug report that is helpful.
When you come across a bug report where you have some expertise, don’t respond with “Works on my machine” with no other follow-up. Confirming that it works on your machine is actually beneficial, but it is more helpful to offer suggestions for what may be different between your machine and the person who filed the bug report. For example, you may want to let the person know which version of the software you have installed or if you have any other setup that may affect the situation.
Sometimes, the best bug report is the one that isn’t written. Before you create an issue, search the issue tracker to see whether someone else already reported the bug. If they did, you may want to add further details to the issue if you see anything missing.
Assuming you didn’t find the issue, it’s time to create a new issue. If the repository has an issue template, you should follow the template as closely as possible.
If is the repository has no template, the following is a good format to follow:
- Describe the observed behavior.
Try to be objective and communicate facts, not opinions.
- Describe what you expected to happen.
How did the observed behavior differ from your expectations?
- Describe detailed repro steps.
This step is the most important part of the bug report. Describe step by step how someone else can reproduce the problem. Try to make the repro steps as minimal as possible. When you encountered the bug, you may have taken ten steps to get there. But it may be possible to reproduce the bug in only five steps. Spending a little time to make sure that you remove any extraneous steps goes a long way into making a good bug report.
- Describe the repro environment.
This step is where you describe the environment where you reproduced the bug such as the operating system and browser. While it’s not necessary to try to reproduce the bug in other environments, repository owners are very appreciative if you do and report on the results.
4. Be Responsive
No matter how good your issue write-up is or your pull request code is, chances are the repository maintained will have some follow-up questions. It’s particularly frustrating for a maintainer to ask for more information only to be greeted by crickets. If you submit an issue, don’t ghost on it. Make sure you make time to follow up and respond to questions from the maintainers.
And the shoe fits both ways. If you are a maintainer, try and be responsive to people who submit issues and pull requests. In some cases, using an automated response to an new issue or pull-request is appropriate if your repository is par- remember ticularly busy. For example, you could use a Probot app to automatically respond to new issues and pull requests with a note letting them know you plan to look at it but that it may take some time.
Being responsive doesn’t necessarily mean you take care of everything right away. It means that you set expectations right away. On either side of the comment, whether you’re a contributor or a maintainer, the only way for the other person to know when to expect changes is if you tell them. Working on remote, asynchronous projects depends heavily on communication. When you’re in an office you can see whether someone doesn’t come in to work for a while and know they are probably on vacation; on GitHub, you don’t have that contextual awareness.
As an added form of communication, keep your profile status up to date if you do plan on going on vacation. For more detail, see Chapter 16.
5. Submit Pull Requests to Correct Documentation
The campsite rule states that one should leave a campsite in better condition than they found it. It’s a good rule to follow not only with campsites, but also with documentation.
Good documentation is often the weak point with an open source projects. Many OSS projects have very few volunteers, and much of their time is taken working on the actual code. This lack of support makes repository maintainers especially appreciative when someone comes along and contributes to the documentation.
Getting involved with improving a repository’s documentation is also a great way to dip your toe into OSS. If you happen to find an error or something missing in a project’s documentation, consider submitting a pull request to the project fixing the error. This contribution leaves the overall OSS ecosystem better off than it was before.
One of the most challenging pieces of documentation to keep up to date is the Getting Started docs that contributors are meant to follow to first get the project setup on their machine. It’s challenging because the maintainers rarely set up the project brand new, unless they get a new machine. As you’re following the steps, don’t be afraid to open a pull request on this documentation if you had to do something different. It can be especially helpful if instructions are different on Mac versus Windows versus Linux and you’re on a machine that the project doesn’t have documentation for yet.
6. Document Your Own Code
Documenting your own code goes a long ways toward making it more accessible to others. Trying to use unfamiliar code can be challenging and time consuming. Good documentation can save people a lot of time and get them up and running with your code quickly. If only 12 people use your code and you save them each one two hours of hassle, that’s a full day saved!
Depending on the platform, many tools generate documentation from comments in code. Javadoc is a famous example for Java code. It requires that you comment public methods and classes with a standard format. By following the format, you can use the Javadoc tool to generate HTML files. JSDoc is another one for JavaScript.
In addition to code documentation, consider other documentation such as the ones we cover in Chapter 9. For example, every repository should have a README.md file that describes what the repository does. It should also have a CONTRIBUTING.md file that describes how to contribute.
7. Give Credit Where It’s Due
Most open source licenses require proper attribution if you make use of the code in your own project. If you use some source code from an open source project, giving credit where it’s due is a legal matter and required by the license.
But to be an effective community member, credit doesn’t end with attribution to comply with a license. In many situations, giving credit demonstrates that you are a classy person.
For example, if someone contributes a feature or bug fix, mentioning the person who fixed it in your release notes is a good idea. For example, GitHub Desktop makes a point to thank people using its GitHub handles and links to the pull request that contributed a fix in its release notes at https://desktop.github.com/release-notes/.
Another great way to give credit is to mention the person who opened an issue that you may have fixed with a pull request. The pull request description will most likely link to the issue, but calling out the person who found the issue in the description is a great way to encourage others to continue to help find bugs.
8. Help Get the Word Out
Many open source projects are small and relatively unknown. If you find a project useful, help get the word out. It not only benefits the project, who may get an influx of new users and contributors, but it benefits the people you tell who may need that very tool.
You don’t need a huge platform to help people get the word out. Maybe your Twitter follower count is relatively small. Don’t let that stop you. The power of network effects can sometimes help a message really take off.
If you write blog posts or publish YouTube videos, you can also mention different projects, your impressions, and maybe even a tutorial on them on these mediums. The goal here is to help people and projects meet.
9. Be Proactive and Mentor Others
GitHub’s community is growing rapidly. New developers are being minted every single day. What this means is a lot of beginners will be on the site. Over time, you will start to accumulate experience that would be very valuable to one of these beginners. Be proactive and offer to mentor others.
For example, if you maintain an open source repository and see that someone is struggling to make a contribution, offer to walk them through the process. Point them to resources and help them along. If you help two people become proficient contributors and community members and they each help two people down the road and so on, you could end up having a huge impact on the community.
Sometimes it can even be effective to jump on a video chat and help someone debug their code in real time! If you’re comfortable with this approach, it can be a great way to meet new people and see for yourself how someone new approaches your project. It may provide insight into how to improve your documentation. One of our favorite video chat services to use for this purpose is https://appear.in. It’s a free, in-browser video chat service that allows for multiple attendees and allows you to share your screen.
10. Contribute Outside of GitHub
Many open source projects have a lot of activity outside of GitHub. Contributing to the community can go beyond creating issues and opening pull requests. For example, as you gain expertise in a topic, consider heading over to StackOverflow. com and answering questions on that topic. Many open source projects have chat rooms associated with the project in Slack or Gitter. It’s a benefit to others if you head over there and offer your ideas.
Talk to maintainers about other ways you can support their work. As you grow in your career as a software developer, you will pick up skills that are valuable to an OSS project. For example, you may help them figure out how to sign a package using Let’s Encrypt. You may help them register a domain name and pay for it. You may help them navigate setting up a Docker container so that others can try out their project with less setup fuss.
Whatever it is, don’t be shy in offering your skills in support of open source projects, especially those that you benefit from.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.