Fail CI when a TODO comes due.
Write a TODO with a trigger. todo-by stays quiet until the trigger fires, then fails the build. Works in any language and any comment style.
| When | Write |
|---|---|
| A feature flag rollout ends on Dec 1 | // @todo-by 2026-12-01 delete the new_checkout flag |
| A runtime reaches end of life in October | # @todo-by 2026-10 drop the Python 3.10 compat shim |
| A deprecated API goes away in the next major | // @todo-by v3.0 remove the deprecated getUser() |
| Code must survive 2.0 and go right after it | // @todo-by >v2.0 remove the 1.x config migration |
| A test is skipped until your bug is fixed | // @todo-by #482 re-enable the flaky upload test |
| You work around a bug in a dependency | // @todo-by https://github.com/acme/http/issues/45 remove the retry workaround |
| You patched a dependency until their fix merges | # @todo-by https://github.com/acme/http/pull/88 drop the vendored patch |
Once a trigger fires:
$ todo-by --online
./src/checkout.ts:14: overdue since 2026-12-01: delete the new_checkout flag
./src/users.ts:3: version 3.0 reached (v3.0): remove the deprecated getUser()
./tests/upload.test.ts:8: #482 is closed (https://github.com/acme/app/issues/482): re-enable the flaky upload test
3 findingsUse it for small, mechanical chores (delete, revert, re-enable) that wait on a date, a release, or an issue. Work that needs an owner or a discussion belongs in your issue tracker.
brew tap alies-dev/todo-by https://github.com/alies-dev/todo-by
brew install alies-dev/todo-by/todo-byOr cargo install todo-by-cli --locked, or a prebuilt binary from Releases. Details in docs/install.md.
todo-by # scan the current directory, exit 1 if anything is due
todo-by --warn 14 # also warn about dates due within 14 days
todo-by --online # also check issue and pull request triggers against GitHubIn CI, run the same command; it prints GitHub annotations inside Actions. A ready workflow is in docs/ci.md.
- Date triggers: accepted formats and early warnings
- Version triggers: constraints and where the current version comes from
- Issue and pull request triggers: tokens, private repositories, failures
- Usage: every flag, output formats, exit codes
- Configuration:
todo-by.tomland environment variables - What gets scanned: ignore rules, dotfiles, binaries
- CI: GitHub Actions workflow and phasing it in
- Install: Homebrew, Cargo, binaries, minimum Rust version
Inspired by phpstan/phpstan-todo-by by Markus Staab.
MIT.