Rules to Better Scrum using GitHub (Issues and Projects) - 15 Rules

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...

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.

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
• Set up automated workflows for your Issues in a project

That's a tonne of awesome features....but it requires a bit of set up, follow these steps to get up and running:

1. Navigate to Projects | Projects (Beta) | New project

1. Now we have a blank slate, we need to setup our Sprint (they call them Iterations). Navigate to + | + New field

3. Select the Iteration field type

4. You will see a window with options for your new Iteration, name it Sprint and enter Start on and Duration.

5. Now add some Issues to the project and then you can assign them to the correct Sprint, by clicking the drop down in the Sprint field.

Note: You can even add Issues from different Repos

6. To add more Sprints, navigate to Settings | Sprint | Add iteration

Note: You can also change Starts on and Duration here

7. To give yourself a better view of things, you might want to create a view that groups by Sprint. Name your current view Backlog then create a new view and name it Sprints
8. To see the Sprints grouped, and the issues ordered by status, click the view drop down and select group:Sprint and sort:Status-asc

9. Voila! You have Scrum all setup! For bonus points check out the workflow screen where you can automate parts of your issue workflow

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:

• On Microsoft Docs - Assign backlog items to a Sprint
• On GitHub Projects

Once the backlog is ready, you should send the Sprint Forecast email to the client.

Sprint emails can be painful because you need to copy and paste data. Moreover, you can easily lose visibility of all your past Sprints.

GitHub issue templates help solve this problem by standardizing the format and location of Sprints.

Let's take a look at how...

Creating an issue template for both your Sprint Review/Retro email and your Sprint Forecast email gives you several advantages.

• Users don't need to copy and paste the template, they simply press "new" and are prompted for information.
• Visibility of all past Sprints is shown in the GitHub issue history
• Let's you edit with Markdown
• Standardizes the Sprint Forecast and Retro/Review process and information included
• You still get an automated email from GitHub, so you don't lose anything by making the switch!

Make your GitHub issue templates follow the format of the rules on Sprint Forecasts and Sprint Reviews then you are good to go.

Give your Sprint issues a special "Sprint" tag so they can be identified in the backlog. Alternatively, you could store them in a separate repo which keeps them apart from your others issues and lets you keep the Sprint emails private if you don't want them in your public repo.

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 suport 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?

• Discuss the backlog
• What to do when it's done?

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.

1. Install the Azure Boards App from the GitHub Marketplace
2. Create the GitHub Action secrets
3. ADO_PERSONAL_ACCESS_TOKEN (Azure DevOps | User settings | Security | Personal access tokens)
   The Azure Personal Access Token requires "read & write" permission for Work Items.
4. GH_PERSONAL_ACCESS_TOKEN (GitHub | Personal settings | Developer settings | Personal access tokens)
   The GitHub Personal Access Token requires "repo" permissions.
5. ADO_ORGANIZATION (https:// ssw .visualstudio.com/SSW.Rules)
   The Organization name is in your Azure DevOps URL.
6. ADO_PROJECT (https://ssw.visualstudio.com/ SSW.Rules)
   The Project name can also be found in your Azure DevOps URL.
7. 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

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:

1. Standard PBI - needed but the outcome is not very interesting: Do the PBI, just following the DoD
2. Interesting to someone - @ mention them
3. 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.

This email is especially important for stakeholders that don't use, want to use, or have access to the project management tools. If they do have access, remember to also @mention them in the PBI update as per Do you know when you use @ mentions in a PBI?

Sometimes the PBI work originated from an email, in which case you should reply to the email instead of starting a new email. This will allow stakeholders to have additional context.

There are many ways to write tasks in PBIs, but the best way is to use tasklists. This allows you to see the progress of the PBI at a glance as well as avoid any unintentional tasks being tracked. Below is the different ways you could write tasks in PBIs.

Video: GitHub Tips - Why YOU should use tasklists (4 min)

Numbering tasks

When sending tasks in email, you might number your tasks to make it clear what you want.

Although this would work in PBIs, it's not the best way to do it in GitHub.

Using checklists

You can use checkboxes in PBIs to create a checklist for tasks

This will show a visual que as to how many tasks you've completed for the PBI.

These tasks are numbered, but if we were to re-order them we'd need to re-number them so the list makes sense again. A better approach to numbering tasks would be to convert a task into it's own issue, this allows you to detail it out further or have more in-depth conversations around the issue specifically.

One of the downsides to using checklists is that any checkbox in the issue description would show up as a task. This means that if you had a checkbox in the description that wasn't a task, it would show up as a task. This is why we recommend using tasklists.

Using tasklists (recommended)

Lastly you should use the tasklist for your tasks, this gives the same advantages as standard checklists without interference from other checkboxes.

Besides the benefits described above, there's also the advantage of having a UI component built specifically to markup a tasklist.

You can see from the UI component there is a convenient button to add a task, easily see who is assigned to tasks; As well as a menu list of options to convert to issue, rename and remove tasks, all through the UI. This is great for team members who don't feel comfortable with markdown.

When you close a PBI, you should always add a comment with some context. This allows everyone else to understand why the PBI was closed and what the outcome was. This is especially important when you are closing a PBI as "Won't Fix" or "Duplicate", but also if you have UI changes, a couple of screenshots can go a long way to help the team understand what was done.

When you look at a PBI, you can navigate through the commits or pull requests that were linked to the PBI. This is great for understanding the code changes, but that doesn't easily show you what the outcome was.

Screenshots are just one of the things that you could add for more context, some other things you could add are:

• Done Videos (see https://www.ssw.com.au/rules/do-you-send-done-videos/)
• Mention if there is relevant documentation that was updated
• Mention any additional context in the pull request that you didn't want to duplicate
• If you'd had a conversation with someone to change the outcome of the PBI, mention as per my conversation with...
• If you are closing a PBI as "Won't Fix" or "Duplicate", mention the PBI that you are closing it as a duplicate of or why you won't fix it

GitHub provides a way to link issues to PRs. This is useful to see what PRs are associated with what issues. However, when you make this link, the issue will close when the PR is merged.

This is not a good idea because it can cause issues to be closed prematurely. This can lead to confusion and lost work.

Issues should not be closed until all the tasks are complete and have a done comment as per Do you close PBIs with context?

Tip: Avoid using closing keywords e.g. "closes #123" or "fixes #123" in PR descriptions. This will automatically link the issue to the PR and close it on PR merge. Instead, use terms like "relates to #123" or "addresses #123" to link the issue to the PR without closing it.

This was a feature GitHub added but it is not a good idea to use it, if you agree the behaviour should be changed, go upvote this discussion https://github.com/orgs/community/discussions/17308