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 private repositories.
  • 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
  • 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>.
    • However, 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/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/Mac OS

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

Usage

  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/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/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
    • repo_owner: The username of the owner of the repo.
      • For example, jhale1805
    • repo_name: The name of the repo.
      • For 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.
    • 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.
      • For 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.
      • For example, 2021-10-22
    • points_label: The prefix for issue labels containing the point value of the issue. Removing this prefix must leave just an integer.
      • For example: Points: (with the space)
  6. Run python src/main.py to generate the burndown chart.
    • This will pop up an interactive window containing the burndown chart, including a button for saving it as a picture.

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.

GitHub

https://github.com/jhale1805/github-projects-burndown-chart