Rules

Secret ingredients to quality software

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

Learn more on Rules to Better Scrum.

  1. GitHub Issues - Do you use Issue Templates?

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

    bad example issue
    Figure: Bad Example - Issue created without a Template

    good example issue
    Figure: Good Example - Issue created from a Template

    list of options
    Figure: Good Example - All the available Issue Template

    For instructions on setting this up:

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

    githubscrumworkflowimproved
    Figure: Good example - GitHub Projects gives you much more powerful project management ability

    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

    newbetaproject
    Figure: Create a new GitHub Project

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

    newfield
    Figure: Create a new field for your Sprint

    1. Select the Iteration field type

    selectiteration
    Figure: Turn this into an Sprint via the Iteration field type

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

    iterationoptions
    Figure: Pick the name and the dates via the Iteration field options

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

    assignpbitodropdown
    Figure: Pick the Sprint you want for your Issues

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

    Note: You can also change Starts on and Duration here

    settingsnav
    Figure: To add a Sprint, Settings | Sprint | Add Iteration

    additerations
    Figure: To add new Sprints, select Settings | Add iteration

    1. 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
    2. To see the Sprints grouped, and the issues ordered by status, click the view drop down and select group:Sprint and sort:Status-asc

    groupandsort
    Figure: To create a list of Sprints add grouping and sorting

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

    workflownav
    Figure: You can enable or disable predefined Workflows

    workflows
    Figure: There are a bunch of predefined workflows (Coming soon: the ability to create your own! )

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

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

    sprintemailtimepro
    Figure: Bad example - Sprint emails can easily become inconsistent and lost in your inbox

    sprinttemplateissues
    Figure: Good example - With GitHub issues it's easy to spin up a Sprint Review or Forecast template

    editsprintforecast
    Figure: Good example - Editing a Sprint Forecast or Review/Retro is super simple and enabled with markdown!

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

    badlabels
    Figure: Bad Example - using Effort labels is not ideal for GitHub Issues

    Learn more about where Effort labels are appropriate with GitHub Projects, which has custom fields.

    extralabels
    Figure: Good Example - Add a few labels beyond the ones that are set based on the Issue Templates

  6. Reading ugly commits is not very pleasant and makes it very confusing when you have to check the commit history.

    2020 09 17 17 19 04
    Bad Example: The commits have no meaning

    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:

    • "πŸ› Fixed emoji engine in language component"
    • "πŸš€ Added emoji filter on Snapchat"
    • "πŸ“„ 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)

    commits with emojis
    Good Example: Great use of emoji and concise message

    See what emojis work best with each topic here: https://gitmoji.dev/

    emojis list
    Figure: Emojis list

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

    email to github issue2
    Figure: Power Automate | Connectors | Github

    email to github issue1
    Figure: Configure Flow connectors to create a new Github Issue from Outlook

    πŸ”₯ Warning: This Flow connector does not suport inline images.

    email to github issue3
    Figure: Good Example - Github issue created from Outlook using Flow connectors

    email to github issue
    Figure: Bad Example - Github issue created using Flow - inline attachment shows up as junk characters

  8. 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 attaionable within one sprint, so splitting an Epic into 2 attainable PBIs is a better option.

    2021 07 30 14 58 22
    Figure: A v2 PBI in GitHub

    2021 07 30 14 59 25
    Figure: A v2 PBI in Azure DevOps

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

    We recommend using software such as GitHub Issues, Azure DevOps, or JIRA to store PBIs straight after or, better yet, during the conversation, rather than using emails that may never be entered into the backlog.

    Typing
    Figure: Get typing during a conversation to make the meeting tangible

    The Product Owner is responsible for owning the Product Backlog. See the video on "Do you know how to be a good Product Owner?"

    1. Emails

    EmailBadExample
    Bad Example - This is a poor way to add a PBI/Issue as you can’t order emails by the business priority

    GitHubIssues
    Figure: Good Example - Github Issues

    3. Azure DevOps - E.g. https://ssw.visualstudio.com

    AzureDevOpsBacklog
    Figure: Good Example - Azure DevOps allows you to enter an item into the backlog, in any priority order

    What's next?

  10. 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
    • ADO_PERSONAL_ACCESS_TOKEN (Azure DevOps | User settings | Security | Personal access tokens) The Azure Personal Access Token requires "read & write" permission for Work Items.
    • GH_PERSONAL_ACCESS_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.
    1. 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

    GitHub Issues Syncing to AzDevOps

    Figure: Good Example - GitHub Issues Syncing 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.

    GitHub PBI Backlog
    Figure: Add the PBI at the top of your backlog

    GitHub PBI Backlog Text
    Figure: Inform users where to add new PBIs

  11. When discussing a PBI/Issue, Pull Request, or a project in general, it is important to do it in the right place.

    Kanban on Screen

    bad mention pbi
    Figure: Bad Example – don't use emails to discuss tasks

    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.

    comment on code in pull request
    Figure: You can add a comment on a specific line of code

    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

    Create Issue
    Figure: Good Example - When adding a GitHub issue, @ mention the Product Owner and other related people so they receive a notification e.g, an email

    For an existing PBI/Issue

    Discuss it in the existing PBI/Issue.

    existing issue discussion
    Figure: You can discuss an existing issue, even when it has been closed

    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

    Discussion Tab in GitHub
    Figure: You can create discussions on your project using the Discussion tab in your GitHub repository

    • In the team channel in Teams

    Team channel
    Figure: You can discuss your idea in Teams on the team channel

    In summary, Email should be the last resort.

We open source. Powered by GitHub