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.
- Once you have a MongoDB instance running, you need to get a URL (known as a “connection string on MongoDB’s Cloud service) to connect to your database. Follow MongoDB’s instructions for how to connect to a cluster.
- Once you have the connection string, copy it and go to your repository’s “Settings” tab, then to “Secrets”
- Click “Add a new secret”, give it the name TODO_ACTIONS_MONGO_URL, and paste in the MongoDB connection sctring.
-
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: hunterboerner/todo-actions@master
env:
TODO_ACTIONS_MONGO_URL: ${{ secrets.TODO_ACTIONS_MONGO_URL }}
- name: Create Pull Request
uses: peter-evans/create-pull-request@v4
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:
- new: This TODO comment is newly added. To ensure that we can reliably track the TODO comment, even when its title or body changes, we need to assign a unique identifier to it.
- identified: This TODO comment has been identified. However a Task has not been created for this TODO comment yet.
- associated: A Task has been created for this TODO comment.
-
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.- To complete a task means “to close an issue,” “to move a card to done,” or “to mark as completed/resolved,” depending on the task management system you use.
-
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 to the repository.