{"id":16568996,"url":"https://github.com/thehale/github-projects-burndown-chart","last_synced_at":"2025-03-21T11:33:40.537Z","repository":{"id":46207998,"uuid":"414903906","full_name":"thehale/github-projects-burndown-chart","owner":"thehale","description":"An easy-to-use burndown chart generator for GitHub Project Boards.","archived":false,"fork":false,"pushed_at":"2024-02-21T05:32:00.000Z","size":166,"stargazers_count":66,"open_issues_count":4,"forks_count":23,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-18T01:07:04.424Z","etag":null,"topics":["agile","burndown","burndown-chart","github","github-projects","hacktoberfest","project-management","scrum"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thehale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-08T08:20:33.000Z","updated_at":"2025-03-07T15:12:37.000Z","dependencies_parsed_at":"2022-07-25T00:02:06.015Z","dependency_job_id":"ffbc3704-2c98-4b32-9a05-e672372b302d","html_url":"https://github.com/thehale/github-projects-burndown-chart","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thehale%2Fgithub-projects-burndown-chart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thehale%2Fgithub-projects-burndown-chart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thehale%2Fgithub-projects-burndown-chart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thehale%2Fgithub-projects-burndown-chart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thehale","download_url":"https://codeload.github.com/thehale/github-projects-burndown-chart/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244792300,"owners_count":20511110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agile","burndown","burndown-chart","github","github-projects","hacktoberfest","project-management","scrum"],"created_at":"2024-10-11T21:12:09.642Z","updated_at":"2025-03-21T11:33:40.285Z","avatar_url":"https://github.com/thehale.png","language":"Python","readme":"# Burndown Chart for GitHub Projects\nAn easy to use [burndown chart](https://www.scrum.org/resources/scrum-glossary#:~:text=B-,burn-down%20chart,-%3A%C2%A0a%20chart%20which) generator for [GitHub Project Boards](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards).\n\n\u003c!-- BADGES --\u003e\n[![](https://badgen.net/github/license/thehale/github-projects-burndown-chart)](https://github.com/thehale/github-projects-burndown-chart/blob/master/LICENSE)\n[![](https://badgen.net/badge/icon/Sponsor/pink?icon=github\u0026label)](https://github.com/sponsors/thehale)\n[![Joseph Hale's software engineering blog](https://img.shields.io/badge/jhale.dev-black.svg?style=plastic\u0026logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNCIgaGVpZ2h0PSI0IiB2aWV3Qm94PSIwIDAgMS4wNTggMS4wNTgiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgY29sb3I9IiMwMDAiIHBhaW50LW9yZGVyPSJmaWxsIG1hcmtlcnMgc3Ryb2tlIj48cGF0aCBkPSJNLjY0My43NTJhLjE1Ni4xNTYgMCAwMC0uMTMuMDU5Qy40NzYuODUuNDcuOTE3LjQ2OS45M2EuMDI1LjAyNSAwIDAwLjAyNi4wMjhoLjA2NmEuMDI1LjAyNSAwIDAwLjAyNC0uMDIuMTIuMTIgMCAwMS4wMi0uMDUyQy42MTguODcuNjMyLjg2OS42NTUuODY5aC4xMjJjMC0uMDAyLjA3Ni4wMDcuMTI5LS4wNUEuMTQzLjE0MyAwIDAwLjkyOC43ODcuMDI1LjAyNSAwIDAwLjkwNi43NTJILjY0M3oiIGZpbGw9IiMwNTAiLz48cGF0aCBkPSJNLjM5My40MWEuMDIuMDIgMCAwMC0uMDIuMDJ2LjI2YzAgLjAxMi4wMDEuMDI5LS4wMTQuMDQ0Qy4zMy43NTkuMjgyLjc1LjI2Ny43MzYuMjU3LjcyOC4yNS43MTMuMjQ0LjY4N0EuMDI1LjAyNSAwIDAwLjIyLjY3SC4xNTNhLjAyNC4wMjQgMCAwMC0uMDI1LjAyNmMuMDA0LjA1Mi4wMjUuMDkuMDUxLjExOWEuMTY3LjE2NyAwIDAwLjExMy4wNTJoLjAzNWEuMTg0LjE4NCAwIDAwLjExNS0uMDVBLjE4Mi4xODIgMCAwMC40OS42OTRWLjQzMUEuMDIuMDIgMCAwMC40Ny40MXpNLjc4Ny4zOWEuMDIuMDIgMCAwMC0uMDIuMDJ2LjI0MmMwIC4wMTEuMDA5LjAyLjAyLjAyaC4wNzdhLjAyLjAyIDAgMDAuMDItLjAyVi40MTFhLjAyLjAyIDAgMDAtLjAyLS4wMnpNLjM5My4yMThhLjAyLjAyIDAgMDAtLjAyLjAydi4wNzdjMCAuMDExLjAwOC4wMi4wMi4wMkguNDdhLjAyLjAyIDAgMDAuMDItLjAyVi4yMzhhLjAyLjAyIDAgMDAtLjAyLS4wMnpNLjU5LjFhLjAyLjAyIDAgMDAtLjAyLjAydi41MzJjMCAuMDExLjAwOS4wMi4wMi4wMmguMDc3YS4wMi4wMiAwIDAwLjAyLS4wMlYuMTJBLjAyLjAyIDAgMDAuNjY3LjF6IiBmaWxsPSIjMDBkNDAwIi8+PC9nPjwvc3ZnPg==)](https://jhale.dev)\n[![](https://img.shields.io/badge/Follow-thehale-0A66C2?logo=linkedin)](https://www.linkedin.com/comm/mynetwork/discovery-see-all?usecase=PEOPLE_FOLLOWS\u0026followMember=thehale)\n\n![Example Burndown Chart](./docs/images/example_burndown_chart.png)\n\n## Table of Contents\n* [Features](#features)\n* [Installation](#installation)\n* [Assumptions](#assumptions)\n* [Configuration](#configuration)\n* [Usage](#usage)\n* [Contributing](#contributing)\n* [About](#about)\n\n## Features\n* Create a **burndown chart for a GitHub Project Board**.\n* Works for projects in **public/private repositories** and **organizations**.\n* Includes a **trend line** for the current sprint.\n* Supports custom labels for **tracking points for issues**\n\n## Assumptions\nThis tool, while flexible, makes the following assumptions about your project management workflow:\n* You use one and only one [GitHub Project Board](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) for each of your [Sprints](https://scrumguides.org/scrum-guide.html#the-sprint)\n* You use one and only one [GitHub Milestone](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) for each of your [User Stories](https://www.scrum.org/resources/blog/user-story-or-stakeholder-story)\n* You use one and only one [GitHub Issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) for each of your [Sprint Backlog Items/Tasks](https://scrumguides.org/scrum-guide.html#sprint-backlog)\n* If you want to track points, each of your GitHub Issues has a [label](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) indicating how many [points](https://www.scrum.org/resources/scrum-glossary#:~:text=several%20ways%20such%20as-,user%20story%20points,-or%20task%20hours.%20Work) its corresponding task is worth.\n    - Furthermore, all labels that indicate point values have the format `\u003cprefix\u003e\u003cint\u003e`.\n    - Multiple labels indicating points on the same Issue are supported.\n* A Sprint Backlog Task is considered [Done](https://www.scrum.org/resources/professional-scrum-developer-glossary#:~:text=D-,definition%20of%20done%3A,-a%20shared%20understanding) if its corresponding GitHub Issue is Closed.\n\n## Installation\n### 0. Clone this repository\n```\ngit clone https://github.com/thehale/github-projects-burndown-chart.git\ncd github-projects-burndown-chart\n```\n### 1. Create a virtual environment\n```\npython -m venv ./venv\n```\n\n### 2. Activate the virtual environment\n\n*Linux/macOS*\n```\nsource venv/bin/activate\n```\n*Windows (Powershell)*\n```\n.\\venv\\Scripts\\activate\n```\n*Windows (Command Prompt)*\n```\n.\\venv\\Scripts\\activate.bat\n```\n\n### 3. Install the dependencies\n```\npip install -r requirements.txt\n```\n\n## Configuration\n### 1. Create a [Personal Access Token](https://github.com/settings/tokens) with the `repo` scope. If Project V2, add `read:project` scope.\nDo not share this token with anyone! It gives the bearer full control over all private repositories you have access to!\n\nThis is required to pull the Project Board data from GitHub's GraphQL API.\n### 2. Make a copy of `src/github_projects_burndown_chart/config/secrets.json.dist` without the `.dist` ending.\nThis allows the `.gitignore` to exclude your `secrets.json` from being accidentally committed.\n### 3. Fill out the `github_token` with your newly created Personal Access Token.\n### 4. Make a copy of `src/github_projects_burndown_chart/config/config.json.dist` without the `.dist` ending.\nThis allows the `.gitignore` to exclude your `config.json` from being accidentally committed.\n### 5. Fill out all the configuration settings\n#### Repository Projects\n`project_name`: A memorable name for your project for use with this tool.\n\n`project_name.query_variables`\n| Variable | Meaning |\n|----------|---------|\n| `repo_owner` | The username of the owner of the repo. \u003cbr/\u003e\u003cbr/\u003e Example: `thehale` |\n| `repo_name` | The name of the repo. \u003cbr/\u003e\u003cbr/\u003e Example: `github-projects-burndown-chart`|\n| `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. \u003cbr/\u003e\u003cbr/\u003e Example: `1` (from [`https://github.com/thehale/github-projects-burndown-chart/projects/1`](https://github.com/thehale/github-projects-burndown-chart/projects/1)) |\n| `column_count` | A number \u003e= the number of columns on the project board. (DEFAULT: 5)\u003cbr/\u003e\u003cbr/\u003e A closer fit improves performance and reduces the chance of rate limiting from GitHub's GraphQL API. If Project V2, it is optional. |\n| `max_cards_per_column_count` | A number \u003e= the maximum number of cards in any column on the project board. (DEFAULT: 50)\u003cbr/\u003e\u003cbr/\u003e A closer fit improves performance and reduces the chance of rate limiting from GitHub's GraphQL API. If Project V2, it is optional. |\n| `labels_per_issue_count` | A number \u003e= the number of labels on any issue on project board. (DEFAULT: 5)\u003cbr/\u003e\u003cbr/\u003e A closer fit improves performance and reduces the chance of rate limiting from GitHub's GraphQL API. |\n\n`project_name.settings`\n| Variable | Meaning |\n|----------|---------|\n| `sprint_start_date` | The first day of the sprint formatted as `YYYY-MM-DD`. \u003cbr/\u003e\u003cbr/\u003e Must be entered here since GitHub Project Boards don't have an assigned start/end date. \u003cbr/\u003e\u003cbr/\u003e Example: `2021-10-08` |\n| `sprint_end_date` | The last day of the sprint formatted as `YYYY-MM-DD`. \u003cbr/\u003e\u003cbr/\u003e Must be entered here since GitHub Project Boards don't have an assigned start/end date. \u003cbr/\u003e\u003cbr/\u003e Example: `2021-10-21` |\n| `chart_end_date` | (OPTIONAL) The last day to show on the burndown chart formatted as `YYYY-MM-DD`. \u003cbr/\u003e\u003cbr/\u003e 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). \u003cbr/\u003e\u003cbr/\u003e Example: `2021-10-24` |\n| `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.\u003cbr/\u003e\u003cbr/\u003e Example: `Points: ` (with the space) |\n| `calculators` | (OPTIONAL) A list of the calculator(s) to use to calculate the point burndown lines to show on the burndown chart. (DEFAULT: [`closed`])\u003cbr/\u003e\u003cbr/\u003e_OPTIONS:_ `closed`, `assigned`, `created`, `taiga`\u003cbr/\u003e\u003cbr/\u003e Example: [`taiga`, `closed`, `assigned`] |\n| `version` | (OPTIONAL) The version number of GitHub Projects to use the burndown chart. (DEFAULT: [`1`])\u003cbr/\u003e\u003cbr/\u003e OPTIONS: `1`, `2`\u003cbr/\u003e\u003cbr/\u003e Example: `2` |\n\n#### Organization Projects\nAll settings are the same as for the [Repository Projects](#repository-projects), except `repo_owner` and `repo_name` are replaced with `organization_name` as shown below.\n\n`project_name.query_variables`\n| Variable | Meaning |\n|----------|---------|\n| `organization_name` | The name of the organization on GitHub as it appears in the URL of their organization page. \u003cbr/\u003e\u003cbr/\u003e Example: `golang` (from https://github.com/golang) |\n## Usage\nGiven 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:\n```\nmake run type=PROJECT_TYPE name=PROJECT_NAME\n```\n\nThis will pop up an interactive window containing the burndown chart, including a button for saving it as a picture.\n\n### Example\nMake a copy of `example.config.json` without the leading `example.`\n\nTo see this repository's example project board:\n```\nmake run type=repository name=burndown_chart_kickoff\n```\n\nTo see Golang's progress on their current roadmap:\n```\nmake run type=organization name=golang_on_deck\n```\n\n### Discord Webhook\nThis project also supports posting the burndown chart to a Discord Webhook. Here's how to set that up:\n1. [Create a webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks#:~:text=Facebook-,making%20a%20webhook,-With%20that%20in) in your Discord server.\n2. Put the webhook's URL into the `discord_webhook` setting in `secrets.json`.\n3. Add the `--discord` option when running the script.\n\n```\nmake run type=repository name=burndown_chart_kickoff opts=\"--discord\"\n```\n\n### Save as file\nThis project also supports saving the burndown chart file. Here's how to set that up:\n1. Add the `--filepath=$filepath` option when running the script.\n\n```\nmake run type=repository name=burndown_chart_kickoff opts=\"--filepath=./tmp/chart.png\"\n```\n\n## Contributing\nContributions are welcome via a [Pull Request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).\n\n*The Legal Part*\n\nBy 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.\n\n## About\nThis 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.\n\nWe hope it will be especially useful to other students in computing-related fields.\n","funding_links":["https://github.com/sponsors/thehale"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthehale%2Fgithub-projects-burndown-chart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthehale%2Fgithub-projects-burndown-chart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthehale%2Fgithub-projects-burndown-chart/lists"}