Turn TODO in source code into issues and close them when they are gone. Runs on GitHub Actions.
Turn TODO comments inside source code into GitHub issues and closes them when they are gone. Runs on GitHub Actions. This project is hugely inspired by 0pdd.
Turns TODO comments into GitHub issues.
A TODO comment looks like this:
// TODO: Add integration test for TodoActionsMain.
//
// Code that interface with external data have been separated into their own modules.
// These includes:
//
// - `DataStore`
// - `CodeRepository`
// - `TaskManagementSystem`
//
// They can be mocked by creating a mock version using `__mocks__` folder.
// https://jestjs.io/docs/en/manual-mocks
…and it gets turned into an issue like this:
The first line is the title. The rest becomes the issue body.
The GitHub issue is updated whenever the text inside the TODO comment changes. This allows elaboration and collaboration on TODO comments.
Once the TODO comment is removed, the corresponding issue is automatically closed. This allows fine-grained task management, and also allows new contributors to easily contribute to the code base.
As a case study, when we used the 0pdd tool on codeforthailand/election-live project, it helped us attract 20+ contributors and visualized the work that got done in just 7 days:
Before you begin, you'll need a running MongoDB instance This action uses MongoDB to keep track of TODO comments and their associated issues.
You can get a free instance on MongoDB Atlas. The same MongoDB database can be used with multiple repositories.
In the repository where you want to set up this action, click the “Actions” tab
On the Actions page, click “Set up a workflow yourself” (If you already have actions set up, click “New workflow” in the left sidebar first.)
This will bring you to the GitHub workflow editor. Copy the below code into the editor:
name: Create issues from todos
on:
push:
branches:
- master
jobs:
todos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: todo-actions
uses: dtinth/todo-actions@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TODO_ACTIONS_MONGO_URL: ${{ secrets.TODO_ACTIONS_MONGO_URL }}
Recommended: Rename main.yml
to something else, such as todos.yml
Complete the workflow creation by clicking “Start commit” and committing the new yml
file to your repo.
Commit your changes. You should see the workflow running on GitHub under Actions tab.
This tool is designed to be task management system-agnostic.
That is, in the future it may be used with tools other than GitHub issues.
Therefore, inside the code base, instead of “issues,” todo-actions
calls them tasks.
TODO comment: A TODO comment inside the source code. It begins with a TODO marker, and followed by a block of text whose first line is the title and the rest is the body.
// TODO: Title here
// Body here
A TODO comment may be in one of 3 stages:
TODO marker: The text that denotes a TODO comment.
It begins with the word TODO
, may contain a reference inside square brackets, and ends with a colon.
In order for the marker to be recognized, it must follow a whitespace, and no alphanumeric character may precede it.
Stage | Example marker |
---|---|
new | TODO: |
identified | TODO [$5d20dc8e6a26d44c2afd08c6]: |
associated | TODO [#1]: |
Repository: A GitHub repository. Don't use the word “project” when you mean “repository.”
Task Management System: e.g. GitHub Issues, GitHub Projects, Trello, Taskworld, JIRA, etc.
Task: A work item inside a Task Management System that can be created and completed by todo-actions
. e.g. an issue, a card, a ticket, or a task.
A push
event causes the action to run in GitHub Actions. If the current branch is master, it continues. Otherwise, it is aborted.
The action scans for TODO
comments.
// TODO: implement this thing
Each new TODO marker is then replaced with a unique ID.
// TODO [$5d20dc8e6a26d44c2afd08c6]: implement this thing
The change is committed and pushed to the repository. If the push is successful, then we have successfully uniquely identified each to-do comment. Otherwise, someone else has made another commit to the repository, and the action is aborted.
For each TODO
marker, create a GitHub issue. Then replace the marker with the issue number.
// TODO [#1]: implement this thing
The change is committed and pushed to the repository. If the push is successful, then it is done. Otherwise, someone else has made another commit to the repository, the action on that commit will take care of committing.