GitHub is a great tool for your development team and especially remote teams, although some of its defaults are less than ideal. The following are some tips and tricks to help make your team even more productive.
GitHub Labels
Although the default labels (bug, dependencies, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question, wontfix) might work for simple projects, they are not great for larger teams. For one, they don’t have good visual hierarchy or gradient color conventions, and two they don’t indicate the severity or size of issues.
So I liked the prefix and color solution proposed by Dave Lunny in Sane GitHub Labels. Using his example I created my own set labels for Type, Priority, Size, Status and App.
Type labels indicate the kind of issue, I selected these different color codes so they are easily distinguishable.
Type: Bug #333333
Type: Design #6a1051
Type: Enhancement #58508d
Type: External #bfdadc
Type: Feature #216583
Type: Maintenance #a0855b
Type: Pull Request #6ba8a9
Type: Question #50b6bb
Type: Research #ac8dafPriority labels specify the level of importance using color codes varying from yellow to red so they are easily identifiable.
Priority: Critical #7c0a02
Priority: High #b22222
Priority: Medium #e88a1a
Priority: Low #f1bc31Size labels indicate the level of effort using shades of green where Small is a few hours, Medium is around a day, and Large is multiple days of effort. Although some people prefer fibonacci points for estimates, I like this approach for its simplicity. For example, you should probably only schedule one Large issue to a person if you’re doing weekly sprints, where as they could probably do a couple Medium issues in a week.
Size: Small #76a665
Size: Medium #227066
Size: Large #265961Status labels using shades of pink to indicate which issues were fixed or not, this is helpful when reviewing old issues that are closed.
Status: Resolved #fad6d6
Status: Unresolved #e99695App labels indicate the source of the issue, which can be helpful when you have multiple repos on the same Project board.
App: Backend #cccccc
App: Frontend #cccccc
App: Database #cccccc
App: Mobile #ccccccTwo nice things about this approach. One, since labels are sorted alphabetically, there is a consistent ordering in every issue. Two, the color conventions makes it easy to instantly identify the severity and size at a glance. Give it a try, I think you’ll love it 😍
Issue Templates
Although GitHub Issues are great, you’ll likely run into the challenge of team members following different conventions and formatting which can get unruly fast.
Issue Templates help solve this problem by allowing you to specify default attributes for your issues. This way issues can be created with pre-defined values.
You can either use GitHub’s editor to create your own templates, or simply created your own markdown files in the .github/ISSUE_TEMPLATE directory. These are the templates I like to use.
.github/ISSUE_TEMPLATE/bug-report.md
This Bug Report template auto labels the issue, plus populated the body with markdown.
---
name: Bug Report
about: Report something that is broken or not working as intended
title: ''
labels: 'Type: Bug'
assignees: ''
---
#### Expected Behaviour
#### Actual Behaviour
#### Steps to Reproduce
-Note, you can specify the Title if you wanted to add a prefix like BUG: but I chose not to since I’m using Labels for this instead.
.github/ISSUE_TEMPLATE/feature-request.md
This Feature Request adds a label and populates the body with markdown.
---
name: Feature Request
about: Suggest an idea for a new feature or enhancement to existing features
title: ''
labels: 'Type: Feature'
assignees: ''
---
#### Describe Problem
#### Suggest Solution
#### Additional Details.github/ISSUE_TEMPLATE/code-maintenance.md
This Code Maintenance template adds a label and default body to the issue.
---
name: Code Maintenance
about: Project cleanup, improve documentation, refactor code
title: ''
labels: 'Type: Maintenance'
assignees: ''
---
#### Describe Problem
#### Suggest Changes
#### Provide ExamplesNow when someone creates a new issue, they can chose from one of these templates.
So the Bug Report would look like this by default, with body pre-populated and a Label set.
.github/pull_request_template.md
Similar to Issue Templates, you can also define Pull Request templates which are also really nice to have.
#### Code Reviewer
#### Related Issue
#### Please Review- [ ]
If you want to learn more about templates, I’d recommend reading GitHub’s documentation, it’s pretty powerful stuff! 💪
GitHub Milestones
Milestones are a great way to group multiple Issues together to track their progress. They can work well when developing a new feature, a development sprint or a product release. Every time an Issue is closed, the progress is automatically updated.
One important thing to note, Milestones are specific to a repo which means they can’t span across multiple repos. So if your development team has multiple repos, for example for API, Frontend and Mobile then GitHub Projects would be better suited for tracking your sprints.
GitHub Projects
Projects follows the kanban process of lists and cards for tracking progress similar to Trello. It’s a great way to see what’s still to do, what’s being worked on and what’s already done.
Since Projects can either be specific to a repo or span multiple repos, it works great for development sprints. Since I preferred doing weekly sprints, I create a board for each week. This allows me to easily schedule issues for upcoming sprints. The progress indicator shows which issues are closed (green), which are in progress (purple) and which haven’t been started yet (grey).
The important thing to note, you will need to manually add Issues (aka cards) to a board. Other GitHub add-ons like ZenHub can automatically add issues to your board, but as a project manager I actually prefer this manual way since they can control what the team is working on for each sprint.
Although you can create a Project board from scratch, I prefer choosing one of the defined templates. Some of the templates also come with nice automations which can conveniently do stuff like move an issue to the Done column when it’s closed.
I personally recommend theAutomated kanban with reviews template, since it works great if your team does code reviews. But every team is different so best to try out each of the templates to see whether they are right for you.
GitHub Actions
Actions are an incredibly powerful way to trigger actions when you push code or close an issue. Although it’s still fairly new, there’s a growing marketplace of actions you can use for everything from deploying to AWS Beanstalk or S3, to posting a message in Slack.
Post Closed Issues To Slack
This action will post to a Slack channel when ever an issue if closed, using the pullreminders/slack-action action.
name: Issue Closedon:
issues:
types: [closed]jobs:
build:
runs-on: ubuntu-lateststeps:
- name: Debug Action
uses: hmarr/debug-action@v1.0.0
- name: Notify Slack
env:
SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
uses: pullreminders/slack-action@master
with:
args: '{\"channel\":\"SLACK_CHANNEL_ID\",\"text\":\"*Issue Closed* ${{ github.event.issue.title }} _(${{ join(github.event.issue.labels.*.name) }})_\",\"attachments\":[{\"text\":\"${{ github.event.issue.html_url }}\"}]}'
Helpful Snippets
Finally here are a few snippets that can help make things a little easier for you.
Pull Request
This snippet helps create a pull request for an issue.
ISSUE_NAME="123 Title of The Issue"
BRANCH_NAME=$(echo $ISSUE_NAME | tr '[:upper:]' '[:lower:]' | tr '/' '-' | tr ' ' '-')
git checkout -b $BRANCH_NAME
git add .
git add -u
git commit -m "Fixed a bug for #123"
git push -u origin $BRANCH_NAMECreate Tag
This snippet creates a tag using a timestamp as it’s name.
TAG_NAME=`date "+%Y-%m-%d_%H-%M-%S"`
git tag -a $TAG_NAME -m $TAG_NAME
git push origin --tagsAnd those are some tips for helping your development team be more productive using GitHub. Are there other tricks you like to use for GitHub? I’d love to hear them in the comments below!
PS If you liked this, give it a few claps 👏
