Rules to Better Scrum using GitHub (Issues and Projects) - 15 Rules
Learn more on Rules to Better Scrum.
GitHub Issues offer a great way of raising Issues within projects. However, it can be difficult to distinguish whether the Issue is a bug, feature request or just a question. GitHub Issue Templates should be used to help standardize Issues and ensure they have enough information for a developer to start work.
Let's take a look at how implementing Issue Templates can improve repository backlogs...
For instructions on setting this up, check out:
GitHub is an awesome place to manage your code, but initially it wasn't the easiest place to manage Scrum. Things improved in 2021 with GitHub Projects.
GitHub Projects lets you create Sprints and manage Issues (aka PBIs or Tasks) with far more power.
Video: Building your backlog with Projects (3 min)
Let's take a look at some of the great new things you can do...
- Track Sprints
- Track estimates
- Add custom fields to Issues
- Collate Issues from multiple Repos
Setting up
That's a tonne of awesome features....but it requires a bit of set up, follow these steps to get up and running:
-
Navigate to Projects | Projects | New project
-
Now we have the option to create a project from a template or from blank. Here is a great template [Template] GitHub Scrum
-
We now want to setup our Sprint iteration. Navigate to Project Settings | Sprint | + Add Iteration
-
You will see your new Sprint created with settings. Click on the field you wish to edit to modify - name it Sprint ‘X’ and enter Start on date and Duration.
-
We can now navigate through the project via the view bar. This will provide us the different dashboards for seperate elements of our projects.
-
To modify a new view, select the down arrow next to the view name. This will allow you to customize views to your desired purpose.
Note: To see the Sprints grouped, and the issues ordered by status, click the view drop down and select group:Sprint and sort:Status-asc
-
Voila! You have Scrum all setup! For bonus points check out the insights screen where we can gather specific data about our teams work.
Prior to your meeting with the customer you should prepare. Get your Sprint Planning (was Release Plan) email ready, so after the meeting you can adjust and promptly send it.
Learn how to create your Sprint backlog:
Once the backlog is ready, you should send the Sprint Forecast email to the client.
Labels are an important way of categorizing your GitHub Issues. However, it is critical to make sure they are useful, clear and do not overwhelm users.
The goal is to use consistent labels across all repos.
Let's take a look at how to make a simple, yet information rich set of labels...
Firstly, set up some GitHub Issue Templates that have default labels. Prefix those ones with "Type:" so it is clear they define the type of Issue:
- Type: Bug
- Type: DevOps
- Type: Documentation
- Type: Feature
- Type: Refactor
Also add some extra labels for important ancillary information. Try not to go overboard though, a good example might be 3:
Some labels to define the area of work:
- Area: Frontend
- Area: Backend
And the standard GitHub label to indicate it is a good Issue for developers new to the project:
- Good First Issue
Learn more about where Effort labels are appropriate with GitHub Projects, which has custom fields.
Reading ugly commits is not very pleasant and makes it very confusing when you have to check the commit history.
Here are a few ways to improve your commit log.
Tip #1: Have a nice, concise comment
Examples:
- Fixed bug with emoji engine
- Added new emoji filter
- Updated Architecture Diagram to have emojis
Tip #2: Using prefixes
Even better is to add a helpful prefix to categorize your commits.
Examples:
- Fix: Fixed bug with emoji engine
- Feature: Added new emoji filter
- Doc: Updated Architecture Diagram to have emojis
Tip #3: Using emojis 💄
In a text message, emojis helps to add emotion and context to plain text. Why not use them in commit messages too 😃?
Examples:
- 🐛 BUG - Fixed emoji engine in language component
- 🚀 Feature - Added emoji filter on Snapchat
- 📄 Doc - Added emoji’s to changelog
There are a bunch more options to choose from - carloscuesta/gitmoji: An emoji guide for your commit messages. 😜 (github.com)
Tip #4: Using gitmoji VSCode extension
Gitmoji - Visual Studio Marketplace (visualstudio.com).
You can even go 🤘 hardcore and use the gitmoji cli - carloscuesta/gitmoji-cli: A gitmoji interactive command line tool for using emojis on commits. 💻 (github.com)
See what emojis work best with each topic here: https://gitmoji.dev/
If a Product Owner sends an email to the development team with a request, that email should be turned into a Github Issue before any work is started or the work is prioritized on the backlog.
Power Automate has a connector to do this automatically when an email arrives in Outlook. It can create a new Github Issue by parsing the From, To, Subject and body of the email.
However, at the moment there is a limitation that it doesn't read inline attachments in emails and therefore you have to create your issues manually in Github.
⚠️ Warning: This Flow connector does not support inline images.
The goal is always to complete Product Backlog Items (PBIs) for the Sprint Review.
Often PBIs grow or change and it does not make sense to deliver what was originally proposed in the Acceptance Criteria.
So think of a way to deliver business value and get it in production, then have a hallway conversation with the Product Owner to see if he agrees with you.
Assuming approval, then adjust some of the Acceptance Criteria, add "v1" to the PBI name and move some of the functionality to a new PBI with the same title and "v2".
e.g.
- Customer and Contact Form v1
- Customer and Contact Form v2
Note: A common example for when to use this is when the full acceptance criteria of a large PBI (or Epic) would not be attainable within one Sprint, so splitting an Epic into 2 attainable PBIs is a better option.
All good Scrum teams have a backlog. The backlog is built by taking a conversation and recording it as one or more Product Backlog Items (PBIs) (e.g. Azure DevOps) or Issues (e.g. GitHub, JIRA).
You should create PBIs during or straight after the conversation, rather than using emails that may never be entered into the backlog.
The Product Owner is responsible for owning the Product Backlog. See the video on "Do you know how to be a good Product Owner?"
Although these requirements come from the Product Owner, it is often the developers who will record these PBIs.
1. Emails
GitHub Issues (Recommended)
3. Azure DevOps - E.g. https://ssw.visualstudio.com
What's next?
If you store all your code in GitHub, why not create all your issues there too?
You might be reluctant to move your backlog to GitHub from Azure DevOps as you don’t want to lose the metrics functionality.
But you can easily sync all your GitHub Issues to Azure DevOps automatically to have the best of both worlds.
Here's a quick guide in setting it up for your GitHub Repository and Azure DevOps.
- Install the Azure Boards App from the GitHub Marketplace
- Create the GitHub Action secrets
- ADOPERSONALACCESS_TOKEN (Azure DevOps | User settings | Security | Personal access tokens)
The Azure Personal Access Token requires "read & write" permission for Work Items. - GHPERSONALACCESS_TOKEN (GitHub | Personal settings | Developer settings | Personal access tokens)
The GitHub Personal Access Token requires "repo" permissions. - ADO_ORGANIZATION (https:// ssw .visualstudio.com/SSW.Rules)
The Organization name is in your Azure DevOps URL. - ADO_PROJECT (https://ssw.visualstudio.com/ SSW.Rules)
The Project name can also be found in your Azure DevOps URL. - Create the following GitHub Action
E.g. SSW uses this template for their projects, you may need to change the new and closed states depending on your environment.
name: Sync issue to Azure DevOps work item on: issues: types: [opened, edited, deleted, closed, reopened, labeled, unlabeled, assigned] jobs: alert: runs-on: ubuntu-latest steps: - uses: danhellem/github-actions-issue-to-work-item@master env: ado_token: "${{ secrets.ADO_PERSONAL_ACCESS_TOKEN }}" github_token: "${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}" ado_organization: "${{ secrets.ADO_ORGANIZATION }}" ado_project: "${{ secrets.ADO_PROJECT }}" ado_wit: "Product Backlog Item" ado_new_state: "New" ado_close_state: "Done" ado_bypassrules: true
Figure: Good Example - GitHub Action to Sync Issues to Azure DevOps
Pros
- Easily manage Sprints and calculate burndown and cycle time
- See all your GitHub Issues and Azure DevOps PBIs in one Backlog
- Automated tagging and hyperlinking between Issues and PBIs
Cons
- The sync is only one-way GitHub Issues -> Azure DevOps Backlog
- It won’t sync existing GitHub Issues unless they are updated
More information about this GitHub Action can be found here https://github.com/danhellem/github-actions-issue-to-work-item
To avoid people adding a PBI to the Azure DevOps, add a PBI at the top of your backlog to indicate that they should add it to GitHub issues.
When discussing a PBI/Issue, Pull Request, or a project in general, it is important to do it in the right place.
For code
Sometimes developers need to discuss code implementations - sometimes to improve the code, other times to explain why something was done a certain way.
This should be done in the Pull Request, if possible comment directly on the line of the code change and once resolved, make sure that the important information is captured in the merge's commit description.
For a new PBI/Issue
As perDo you know when you use @ mentions in a PBI? - Create a new issue mentioning the Product Owner and the related people
For an existing PBI/Issue
Discuss it in the existing PBI/Issue.
For other topics (brainstorm ideas, general discussion, etc.)
You can:
-
Create a PBI/Issue
- use a "discussion" label so that others know that it is just a discussion point and not actionable work yet
- have it checked by the client before publishing it (recommended)
- Discuss it in the discussion tab in GitHub
- In the team channel in Teams
In summary, Email should be the last resort.
-
Key updates on projects may include Done Videos, critical text additions, or specification documents. Typically, links to these deliverables would be added to the PBI that they relate to and the relevant people would be mentioned.
Not every PBI will require an email, but if it is a key update or deliverable, it should be escalated. The developers would make this judgement call, although this could also be added upfront by the Product Owner in the Acceptance Criteria for the PBI. Here are the 3 scenarios:
- Standard PBI - needed but the outcome is not very interesting: Do the PBI, just following the DoD
- Interesting to someone - @ mention them
- Really important - Make sure it’s top of mind, email it
For example, you can send an email similar to this to share a new Done Video to the relevant stakeholders. If you working on a big system or internal projects, include the feature area or project name in the subject for additional context.
To: {{ PRODUCT OWNER }}; {{ OTHER STAKEHOLDERS }} Subject: