About

scrum is a simple command line utility that provides useful scrum metrics to assist a Scrum team in their Transparency, Inspection and Adaptation.

Like Scrum, scrum is lightweight and simple to understand. Unlike Scrum, scrum is easy to master.

Why

There are many issue tracking and "agile" tools in the wild. In many cases these tools are actually wild in one or more of the following ways:

• complexity
• cost
• ignorant simplicity
• integration

These tools usually sit further away from where the end result is happening in code.

GitHub provides simple and lightweight Issue Tracking and Project Management but lacks useful reporting that helps a Scrum team inspect and adapt.

If you are already using GitHub why introduce cognitive complexity by having another tool for project management. Keep everything in one place - the code, the issues, the wiki, the reporting.

Features

Sensible defaults, easily configurable.

Initializing Scrum

In scrum you can declaratively define the components of your GitHub repository including:

• Project Board structure

• Issue Labels

• Project Wiki Pages

• Static site for the reporting Dashboard

Starting a Sprint

Tell scrum when you are starting your Sprint and the duration and scrum will:

• Create a GitHub Milestone, with the Sprint end date and Sprint Name

• Create a boilerplate Wiki page for the retrospective

• Create a Google Calendar event with the team as invitees for:

  • Sprint Planning
  • Daily Scrum
  • Sprint Review
  • Sprint Retrospective

• Populate a Card on a GitHub Project Board with the Sprint Goal

Ending a Sprint

When your Sprint ends scrum will:

• Close the Milestone on GitHub

• Unset the Sprint Goal from the Project Board

• Ask if you want to automatically start a new Sprint.

• Archive the old Sprint configuration.

Transparency

scrum produces useful documents that help improve Transparency, namely:

• Burndown/up Chart

• Sprint Velocity

• Defects trend (requires the label type: bug)

Dashboard

Utilizing GitHub Actions scrum can automatically run and build a reporting dashboard that compares two points in time. This helps all team members ask better questions such as "What has moved since yesterday?".

This reporting dashboard is published as a static site to GitHub Pages or any other static site hosting provider.

The GitHub Action that triggers a Dashboard build can be generated by a variety of events or a cron schedule. Useful if you want to have a dashboard updated on a ticket transfer event or built 5 minutes before your Daily Scrum event.

You can even build your dashboard into part of your CI/CD pipeline.

Usage

scrum is a small CLI with only a few simple commands:

$ scrum help
Scrum is a tool for accelerating Scrum teams that use GitHub.

Usage:

        scrum <command> [arguments]

The commands are:

        auth        authenticates `scrum` with GitHub using OAuth.
        init        initialize a GitHub repo with a `scrum` configuration.
        next        starts a new sprint.
        close       stops a sprint. Primarily used to cancel a sprint.
        report      generate a useful report based on the scrum activity.

Use "scrum help <command>" for more information about a command.

Important Files

All scrum configuration resides in .scrum/ directory and should be committed to .git.

The .scrum folder consists of:

• config.yaml

• scrum.yaml

• events/

• participants.yaml

config.yaml

The config yaml contains the authentication information to connect to GitHub.

scrum.yaml

The scrum.yaml describes the desired state of your GitHub Project. Labels are set a key:value pairs to enable parsing for reports.

# scrum.yaml
board:
  columns:
    - Todo
    - In Progress
    - Peer Review
    - QA
    - Done

labels:
  point: # generates labels such as `point: 0`, `point: 1` ... with the label color `#f9d0c4`
    - 0
    - 1
    - 2
    - 3
    - 5
    - 8
    - 13
    - 20
    - 40
    - 100
    color: '#f9d0c4'
  type:
    - epic
    - user-story
    - tech-story
    - bug
    color: '#cfg0c4'

wiki:
  - Home
  - Sprints # When a Sprint is started a wiki page is added under the `Sprints` page. One wiki page per sprint.

events/current.yaml

The events directory contains the data for the current sprint in a declarative format. Historic sprint definitions in previous sub-directory.

# current.yaml
events:
  type: sprint
  name: "Curious Penguin" # names can be automatically generated
  goal: "Our sprint goal is to add customer value."
  details:
    start: "2020-04-01"
    duration:
      value: 21
      unit: days
    frequency: once

  type: daily
  name: 'Daily Scrum'
  details:
    start: "2020-04-01"
    duration:
      value: 15
      unit: minutes
    frequency: daily

  type: planning
  name: 'Sprint Planning'
  details:
    start: "2020-04-01"
    duration:
      value: 4
      unit: hours
    frequency: once

  type: retro
  name: 'Sprint Retrospective'
  details:
    start: "2020-04-22"
    duration:
      value: 4
      unit: hours
    frequency: once

  type: review
  name: 'Sprint Review'
  details:
    start: "2020-04-22"
    duration:
      value: 4
      unit: hours
    frequency: once

wiki: # define the generally structure of the Sprint wiki page. All the Sprint documentation lives on a single wiki page.
  headings:
    - Goal
    - Retrospective

participants.yaml

participants.yaml defines groups of individuals that may be invited to Scrum events.

#participants
team: &team
  "Joe Blogs": userA@company.com
  "John Doe": userB@company.com
  "Chuck Norris": userC@company.com

daily: # if there is a matching value for the `type` key in `scrum.yaml` these participants will be added to the invite list when scheduling events.
  <<: *team

planning:
  <<: *team

review:
  <<: *team
  "Jane Doe": stakeholder@external.com

retro:
  <<: *team

scrum can also reference a secured remote url to fetch the participants list if committing emails into git history is a concern.