Your project's presence on GitHub signals to others that you're invested in its success and that as a result they, too, can contribute to that success. Simply having your project on GitHub isn't the only way to promote collaboration, GitHub features multiple ways to reduce the "onboarding" for your repository. Even in enterprise situations, providing input on another team's repository can seem like a daunting task for veteran and first-day employees, so, use the power of GitHub to throw down a welcome mat and increase cross-team collaboration.
One of the features of GitHub is the ability to include issue and pull request templates. These enable contributors to provide the information you identified that you need when they create a new issue or pull request on the project. To get a better sense of what a contributor would see when creating a new issue, check out these examples:
In this first example, the development team hasn't implemented an issue template on their repository, so when a potential (or existing) contributor open an issue they are greeted with this blank canvas:
While a blank canvas can be great in an artistic sense, it creates deficiencies in the issue and pull request process. If you don't provide guidelines that your team needs, you lose clarity and needlessly increase context-seeking communication. For example, when someone reports a bug, you might want them to include their operating system, the version of the application, or other environment variables that will help you pinpoint the problem. For new feature requests, you might need the issue author to identify specific use case information that they may or may not describe when starting from scratch.
In this next example, a team was frustrated by the inconsistent way contributors were reporting bugs and requesting features, so they created issue templates. The most important effect these templates have is it improves the consistency in which the team receives the information they need.
With an issue template, you take emptiness out of the equation and guide your users towards the kind of participation you're looking for.
GitHub supports multiple issue templates, so within our groups we are going to create a bug, issue, and custom template for issues created in our repository. While creating these issue templates, it is important to remember the GitHub Flow, so the template should be created on a branch, submitted as a pull request to receive feedback from the team, and merged into the main branch.
Before creating the template, it might be helpful to find existing issue templates on other open source projects on GitHub to get some inspiration. Below are some examples of issue templates found on GitHub:
To create an issue template, perform the following:
- On GitHub, navigate to the main page of the repository
- Under the repository name, click the Settings tab
- In the "Features" section, under "Issues," click the green Set up templates button
- Use the Add template drop-down menu to select the type of template you'd like to create
- To preview or edit the template before committing it to the repository, click Preview and edit
- To edit the template, click the pencil icon located next to the issue name, and type in the fields to edit their contents
- When you're finished editing and previewing your template, click Propose changes in the upper right corner of the page
- Enter a commit message describing your changes
- Below the commit message fields, decide whether to commit your template directly to the default branch, or to create a new branch and open a pull request. For more information about pull requests, see "About pull requests."
- Click Commit changes. Once these changes are merged into the default branch, the template will be available for contributors to use when they open new issues in this repository
Share and receive feedback on the issue template from other class participants via a pull request.
Issue and pull request templates were mentioned as ways to improve the experience contributors have in your repository, but there are other GitHub features that can be helpful as well.
- Labels are a visual way to categorize issues and pull requests in the repository. A repository will come equipped with a handful of default labels out of the box, but new ones can be created (and deleted) as needed to better organize your repository.
- Contributing provides an easily accessible description of how someone should contribute to a repository. This document is automatically linked to when an issue or pull request is opened.
- License are very important when a user considers open sourcing a project, although most internal projects might not need a license applied to them.
In the answer-this repository, create a new label that can be applied to existing or future issues and pull requests. Some examples of labels that could be helpful include:
- documentation needed
- beginners welcome
- specific release versions
- escalated items
To create a label, perform the following:
- From the Issues or Pull requests tab, click Labels
- Click New label
- Enter a Label name, Description, and Color for your new label
- Click Create label