todo2issue
v1.2.1
Published
CLI tool for in-code TODO synchronization to GitHub issues
Downloads
126
Maintainers
Readme
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": {
"[email protected]": "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 withGITHUB_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