Burndown Chart for GitHub Projects

An easy to use burndown chart generator for GitHub Project Boards.

Table of Contents

• Features
• Installation
• Assumptions
• Configuration
• Usage
• Contributing
• About

Features

• Create a burndown chart for a GitHub Project Board.
• Works for projects in public/private repositories and organizations.
• Includes a trend line for the current sprint.
• Supports custom labels for tracking points for issues

Assumptions

This tool, while flexible, makes the following assumptions about your project management workflow:

• You use one and only one GitHub Project Board for each of your Sprints
• You use one and only one GitHub Milestone for each of your User Stories
• You use one and only one GitHub Issue for each of your Sprint Backlog Items/Tasks
• If you want to track points, each of your GitHub Issues has a label indicating how many points its corresponding task is worth.
  • Furthermore, all labels that indicate point values have the format <prefix><int>.
  • Multiple labels indicating points on the same Issue are supported.
• A Sprint Backlog Task is considered Done if its corresponding GitHub Issue is Closed.

Installation

0. Clone this repository

git clone https://github.com/thehale/github-projects-burndown-chart.git
cd github-projects-burndown-chart

1. Create a virtual environment

python -m venv ./venv

2. Activate the virtual environment

Linux/macOS

source venv/bin/activate

Windows (Powershell)

.\venv\Scripts\activate

Windows (Command Prompt)

.\venv\Scripts\activate.bat

3. Install the dependencies

pip install -r requirements.txt

Configuration

1. Create a Personal Access Token with the repo scope. If Project V2, add read:project scope.

Do not share this token with anyone! It gives the bearer full control over all private repositories you have access to!

This is required to pull the Project Board data from GitHub's GraphQL API.

2. Make a copy of src/github_projects_burndown_chart/config/secrets.json.dist without the .dist ending.

This allows the .gitignore to exclude your secrets.json from being accidentally committed.

3. Fill out the github_token with your newly created Personal Access Token.

4. Make a copy of src/github_projects_burndown_chart/config/config.json.dist without the .dist ending.

This allows the .gitignore to exclude your config.json from being accidentally committed.

5. Fill out all the configuration settings

Repository Projects

project_name: A memorable name for your project for use with this tool.

project_name.query_variables

Variable	Meaning
repo_owner	The username of the owner of the repo. Example: thehale
repo_name	The name of the repo. Example: github-projects-burndown-chart
project_number	The ID of the project for which you want to generate a burndown chart. This is found in the URL when looking at the project board on GitHub. Example: 1 (from https://github.com/thehale/github-projects-burndown-chart/projects/1)
column_count	A number >= the number of columns on the project board. (DEFAULT: 5) A closer fit improves performance and reduces the chance of rate limiting from GitHub's GraphQL API. If Project V2, it is optional.
max_cards_per_column_count	A number >= the maximum number of cards in any column on the project board. (DEFAULT: 50) A closer fit improves performance and reduces the chance of rate limiting from GitHub's GraphQL API. If Project V2, it is optional.
labels_per_issue_count	A number >= the number of labels on any issue on project board. (DEFAULT: 5) A closer fit improves performance and reduces the chance of rate limiting from GitHub's GraphQL API.

project_name.settings

Variable	Meaning
sprint_start_date	The first day of the sprint formatted as YYYY-MM-DD. Must be entered here since GitHub Project Boards don't have an assigned start/end date. Example: 2021-10-08
sprint_end_date	The last day of the sprint formatted as YYYY-MM-DD. Must be entered here since GitHub Project Boards don't have an assigned start/end date. Example: 2021-10-21
chart_end_date	(OPTIONAL) The last day to show on the burndown chart formatted as YYYY-MM-DD. Used to change the end date of the chart without affecting the slope of the ideal burndown line (e.g. to show tasks that were completed after the official end of a sprint). Example: 2021-10-24
points_label	(OPTIONAL) The prefix for issue labels containing the point value of the issue. Removing this prefix must leave just an integer. If set to null, the burndown chart will count open issues instead of points. Example: Points: (with the space)
calculators	(OPTIONAL) A list of the calculator(s) to use to calculate the point burndown lines to show on the burndown chart. (DEFAULT: [closed]) OPTIONS: closed, assigned, created, taiga Example: [taiga, closed, assigned]
version	(OPTIONAL) The version number of GitHub Projects to use the burndown chart. (DEFAULT: [1]) OPTIONS: 1, 2 Example: 2

Organization Projects

All settings are the same as for the Repository Projects, except repo_owner and repo_name are replaced with organization_name as shown below.

project_name.query_variables

Variable	Meaning
organization_name	The name of the organization on GitHub as it appears in the URL of their organization page. Example: golang (from https://github.com/golang)

Usage

Given that PROJECT_TYPE is one of [repository, organization] and PROJECT_NAME matches a key in the config.json under the chosen PROJECT_TYPE, run the following command:

make run type=PROJECT_TYPE name=PROJECT_NAME

This will pop up an interactive window containing the burndown chart, including a button for saving it as a picture.

Example

Make a copy of example.config.json without the leading example.

To see this repository's example project board:

make run type=repository name=burndown_chart_kickoff

To see Golang's progress on their current roadmap:

make run type=organization name=golang_on_deck

Discord Webhook

This project also supports posting the burndown chart to a Discord Webhook. Here's how to set that up:

1. Create a webhook in your Discord server.
2. Put the webhook's URL into the discord_webhook setting in secrets.json.
3. Add the --discord option when running the script.

make run type=repository name=burndown_chart_kickoff opts="--discord"

Save as file

This project also supports saving the burndown chart file. Here's how to set that up:

1. Add the --filepath=$filepath option when running the script.

make run type=repository name=burndown_chart_kickoff opts="--filepath=./tmp/chart.png"

Contributing

Contributions are welcome via a Pull Request.

The Legal Part

By submitting a contribution, you are agreeing that the full contents of your contribution will be subject to the license terms governing this repository, and you are affirming that you have the legal right to subject your contribution to these terms.

About

This project was first created by Joseph Hale (@thehale) and Jacob Janes (@jgjanes) to facilitate their coursework in the BS Software Engineering degree program at Arizona State University.

We hope it will be especially useful to other students in computing-related fields.