Todo 2 Issue

CLI tool to synchronize code-base TODO into GitHub issues.

What does it do?

At the first run, it:

• finds TODOs and FIXMEs in your code
• groups them using their text
• creates a GitHub issue for each group with a specific label
• optionally assigns a user to the issue based on the author of the label (see authorsByEmail configuration option)
• references the issue in the code-base like TODO(#123) Do something

When ran again, it:

• discovers new TODOs and handles them with the steps above
• updates GitHub issues with current location of the TODOs (file and line)
• closes GitHub issues with no corresponding TODO in the code-base

The tool works with a sub-set of issues tagged by a specific label (by default that is TODO). This label should not be assigned to issues manually, because such issues will be closed on the next run as there are no corresponding TODOs in the code-base.

Installation

npm i todo2issue --save-dev

or

yarn add todo2issue --dev

Configuration

The tool is configurable through package.json.

Repository

First you need to ensure that the repository property is present and properly populated:

{
  // ...
  "repository": {
    "type": "git",
    "url": "git+https://github.com/salsita/todo2issue.git"
  },
  // ...
}

Preferences

Then you should configure behavior of the tool using todo2issue property:

{
  // ...
  "todo2issue": {
    "filePatterns": [
      "**/*.ts?(x)",
      "**/*.js?(x)"
    ],
    "issueLabel": "TODO",
    "branch": "develop",
    "authorsByEmail": {
      "[e-mail]": "goce-cz"
    }
  },
  // ...  
}

• filePatterns - a list of glob patterns matching files in which the tool should search for TODOs
  • .gitignore files are respected
  • defaults to ['**/*.[tj]s?(x)'] (JavaScript and TypeScript files)
• issueLabel - name of the label that defines a set of GitHub issues governed by the tool
  • this label should not be used for anything else than for the purpose of this tool
  • this label MUST NOT be assigned / unassigned manually
• branch - name of the branch to be used when referencing code from the generated issues
  • defaults to active Git branch, but it is highly recommended fixing this in the config
• authorsByEmail - mapping between email of a commit author and a GitHub username
  • if present, authors of TODOs are assigned to the created issues
  • if present, and a mapping for particular email is missing, the sync fails (can be overridden by --ignore-unresolved-users)
  • if the emails and/or usernames are considered sensitive, one can supply the mapping as a JSON object serialized into a AUTHORS_BY_EMAIL environment variable

GitHub token

The tool needs GitHub personal access token to interact with GitHub API on your behalf. You can provide it in various ways:

• through an GITHUB_TOKEN environment variable
• through .env file with GITHUB_TOKEN variable
  • needs reside in the directory where the tool is executed
• through the --token command line option

Usage

Ensure you're running the commands in the root directory of your project - where package.json resides.

Full sync

Simply run the tool with no parameters:

todo2issue

This will perform create, update and close issues using the configuration specified in package.json. Newly discovered TODOs will be updated to reference the issues that were created. This will yield a change in the code-base. Make sure you commit and push these changes.

Dry-run

todo2issue --dry-run

This will simulate the full sync, but it won't write anything to GitHub. Todos will still be updated with references, but the issue numbers will be just sequentially generated locally.

This is useful for validating settings and TODO discovery. Each mocked operation is also logged into the console, and you can review the issues about to be created in detail before running the sync for real.

DO NOT COMMIT the generated changes from a dry-run since the TODOs don't reference actual issues, but rather some fake numbers.

ROLL BACK the changes before making a real sync!

Help

The tool's commandline API is self-descriptive through the standard --help option.

todo2issue --help