Each GitHub repo can contain multiple Issue templates to help teams organize incoming requests. These templates can be used in ZenHub Workspaces to help organize work and ensure the right details are being captured in various scenarios.
Creating templates in a repo
To create multiple Issue templates in a repository, you'll need to be a repo admin. GitHub Issue Templates live in the Settings tab of the repo. Once in Settings, click on Set up templates under the Issues section on the main options page.
By default, GitHub provides three options: Bug report, Feature Request, and a custom template. There's no limit to how many templates you can create, these are just smart defaults to help you get started!
To preview or edit the existing templates GitHub adds, click Preview and Edit next to the defaults. You can also use the trash can to delete the templates and use the Custom template option to create your own. We've shared templates below for bug reports, feature requests, Epics, and more below!
Templates are styled using Markdown
Here's a list of the non-alphabetic characters that are used in Markdown, their corresponding names, and what styling they're used for.
- #Hashtag (Used to create Headers or to reference another Issue) (ie. ## Title 1 creates an underlined title)
- *Asterisk (Put a * on each side of the text you'd like to bold)
- _Underscore (Put a _ on each side of the text you'd like to _italicize_)
- ~Tilde (Put a ~ on each side of the text you'd like to strikethrough).
- [Opening square brackets, and ]Closing square brackets are used to make checklists (Using - [ ] will create checklist items that can be ticked off in the Issue)
- ‐Dash (One dash is used before text to make an unordered list. Three dashes in a row between paragraphs is used to make a line)
- >Greater-than symbol (Used in front of text that you'd like to transform into a quote)
- @Mention character (Used to reference another user)
- `Backtick (Put 3 ` on either side of code to create snippets of code and have them appear as one block)
View the complete Markdown guide here.
Once in Preview and edit mode, click the pencil icon next to the template title to modify the content of the template.
When editing, add an About description to help your team or contributors understand the use case and how to use the template. This description will appear when teams create New Issues and helps guide the individual to the right template so be as descriptive as possible (especially if you work in a public repo!).
Once published, when creating new Issues the description appears both in GitHub and ZenHub.
Committing your changes to make the new templates live
When you have created and edited your templates, you need to Propose changes to push them live. Each template acts like a code change in the repository, which is why they need to be proposed as changes to the repo's code.
We recommend not directly merging to staging or master unless you're confident you will not be breaking production code
If this is a repo that has live code for your product and you are making changes, it's highly recommended you create a new branch for your changes instead of committing directly to a staging or master branch. This will ensure that this, like any other code change in the repo, goes through proper testing, code review, and your team's merge process.
When creating a new branch, be descriptive so the rest of the team knows what it's for. Adding a commit message will also ensure there's enough details for the team.
Committing changes under a new branch means you'll need to create a Pull Request, requesting to merge that branch in with the rest of your staging and master code.
Once live, templates are available from the Issues tab in GitHub as well as in ZenHub when creating new Issues via the template dropdown.
Template library
Feel free to copy and modify any of the templates below to suit your team's needs.
Bug Reports
Use this template to capture relevant information to track bug reports consistently and add priority and business value to better organize Sprints and work.
## Priority + Rationale
(To be filled out after bug submission by a product owner)
- Add stats if available on % of customers impacted
- Is this visible by all customers, or in a high traffic area?
- Is this tech debt?
- If applicable, what % of revenue is possibly impacted by this?
## Describe the bug
A clear and concise description of what the bug is.
## Steps to Reproduce
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
## What do you believe the expected behavior is
A clear and concise description of what you expected to happen.
## Relevant screenshots
If applicable, add screenshots to help explain your problem.
## Platform details
Where is this occurring and more details about the environment (computer setup) of the customer.
**Desktop (please complete the following information):**
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22 or web app]
**Mobile (please complete the following information):**
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
- Browser [e.g. stock browser, safari]
- Version [e.g. 22]
## Additional context
Add any other context about the problem here.
Feature Requests
Use this template to help streamline the information you collect from stakeholders who submit requests, enhancements, or product improvements.
## Describe the ideal solution or feature request
A clear and concise description of what the customer wants to happen.
## Difficulty, impact, and usage score
| Technical difficulty | User goals | Usage frequency |
|--------------------| --------------------| --------------------|
| ie. Small, medium, large (filled out after submission) | ie. How important is this to the user, what the user wants to accomplish | ie. Daily, weekly, monthly |
## How does this tie into our current product?
Describe whether this request is related to an existing workflow, feature, or otherwise something in the product today. Or, does this open us up to new markets and innovative ideas?
## Who asked for this?
Add more on who asked for this, ie. company, person, how much they pay us, what their tier is, are they a strategic account, etc.
Epic template
Use this template to streamline information you track about large projects and user stories. New to Epics? Get an overview
## Description
Brief summary of what this Epic is, whether it's a larger project, goal, or user story. Describe the job to be done, which persona this Epic is mainly for, or if more multiple, break it down by user and job story.
## Initiative / goal
Describe how this Epic impacts an initiative the business is working on.
### Hypothesis
What is your hypothesis on the success of this Epic? Describe how success will be measured and what leading indicators the team will have to know if success has been hit.
## Acceptance criteria and must have scope
Define what is a must-have for launch and in-scope. Keep this section fluid and dynamic until you lock-in priority during planning.
## Stakeholders
Describe who needs to be kept up-to-date about this Epic, included in discussions, or updated along the way. Stakeholders can be both in Product/Engineering, as well as other teams like Customer Success who might want to keep customers updated on the Epic project.
## Timeline
What's the timeline for this Epic, what resources are needed, and what might potentially block this from hitting the projected end date.