CLI tool to synchronize code-base TODO into GitHub issues.
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
authorsByEmailconfiguration 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.
npm i todo2issue --save-devor
yarn add todo2issue --devThe tool is configurable through package.json.
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"
},
// ...
}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.gitignorefiles 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_EMAILenvironment variable
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_TOKENenvironment variable - through
.envfile withGITHUB_TOKENvariable- needs reside in the directory where the tool is executed
- through the
--tokencommand line option
Ensure you're running the commands in the root directory of your project - where
package.json resides.
Simply run the tool with no parameters:
todo2issueThis 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.
todo2issue --dry-runThis 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!
The tool's commandline API is self-descriptive through the standard --help option.
todo2issue --help