Burndown Chart for GitHub Projects
An easy to use burndown chart generator for GitHub Project Boards.
Table of Contents
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.
- Furthermore, all labels that indicate point values have the format
- A Sprint Backlog Task is considered Done if its corresponding GitHub Issue is Closed.
Installation
0. Clone this repository
git clone https://github.com/jhale1805/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.
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: jhale1805 |
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/jhale1805/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. |
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. |
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, taigaExample: [ taiga, closed, assigned] |
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:
- Create a webhook in your Discord server.
- Put the webhook's URL into the
discord_webhooksetting insecrets.json. - Add the
--discordoption when running the script.
make run type=repository name=burndown_chart_kickoff opts="--discord"
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 (@jhale1805) 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.