If you do any work – regardless of if it’s open source or closed source – (though I know most who use read this site are involved in open source), you likely use some source control, and it’s probably GitHub.
For many of you, you either follow a project, contribute to a project, or handle pull requests to a project. And what about those projects that you work on with a team?
Perhaps your workflow is something like this:
- you create a branch to work on a feature,
- you push the branch to detail the work you’ve done for a peer to review,
- the review is merged,
- you carry on.
But what do you put in the template for the pull request? Is it the same every time or is it different? What about if the content of the PR is related to something in Trello, Asana, Basecamp, or some other project management system?
That’s where GitHub PR templates come into play.
GitHub PR Templates
You can read all about ’em on the page, but here’s the gist (no pun intended):
It’s hard to solve a problem when important details are missing. Now project maintainers can add templates for Issues and Pull Requests to projects, helping contributors share the right details at the start of a thread
And the idea is simple: We create templates for issues and pull requests for others that provide a level of information that they must fill out before submitting an issue or a pull request.
This helps us, as maintainers know whatever information it is that we require before looking into it. Further, it may allow us to link to a prior issue, previous ticket, prior anything related to the project.
Case in point, let’s say you’re working on a project and you want to include the following information:
- a short description of what the PR does so the maintainer doesn’t have to guess,
- the status of the PR on if it should be ready to be merged or if it’s still in development but ready for some review,
- a link to the ticket in your project manager to which the PR is relevant.
I’m not saying that this is the information that’s required, but it’s something we’ve used, and I’ve found useful (and it’s nice to see more improvements being made over time).
But How Do We Use This?
The site is pretty clear, but it’s really simple. You need the following files in your project directory or in your project’s .github directory:
Each of these should be markdown files that stub out exactly what it is that you’re looking for your contributors to include whenever they are, y’know, contributing to your project in some way.
And then, whenever a user looks to report an issue or create a pull request, they have prompted with the information from the template.
Nice, isn’t it?
It’s Not Much, But…
You may not think it’s much, but it’s a pretty easy to help improve the quality of the information coming into a project, have your contributors think about what they are putting into the project, and then respond accordingly.
Plus, it helps you and the rest of your team understand what it is that’s about to be reviewed and to prepare for any changes that may come their way when working on these projects.