Skip to content

Rework README so the first screen explains the tool - #34

Merged
alies-dev merged 1 commit into
mainfrom
docs-readme-ten-second-skim
Oct 20, 2026
Merged

alies-dev merged 1 commit into
mainfrom
docs-readme-ten-second-skim

Conversation

@alies-dev

Copy link
Copy Markdown
Owner

Context

The README's first screen didn't say what the tool is for. It opened with "Flag todo-by tags whose deadline has passed, …", then two sections (Idea, What it's for) on the motivation, and the first example covered dates only. Install sat below all of that. The example was also wrong: it showed a .js and a # comment, then printed a finding from config/legacy.yml:42 with a deadline that neither comment had.

Further down, the README copied the version and issue syntax tables from docs/versions.md and docs/issues.md, and gave one dense paragraph to scan rules (symlinks, VCS metadata, named paths).

Solution

  • The top is now a one-line pitch ("Fail CI when a TODO comes due"), then three tags (date, version, issue) and the output of one todo-by --online run. I captured the output from a real run against a merged PR in this repo, then rewrote the issue line to a neutral #123 in acme/app. The message format is unchanged.
  • Install comes next, then a short Usage block with the common invocations and a pointer to todo-by --help for the rest.
  • Idea and What it's for are merged into a shorter When to use it, placed after Usage.
  • Trigger sections keep one example and the main rule each. The full syntax tables now live only in docs/versions.md and docs/issues.md. Dates keep their table, since no docs page covers them.
  • The scan rules moved to a new docs/scanning.md. The README keeps a two-sentence summary. The | head / pipefail exit-code note moved to docs/ci.md.
  • Code comments that pointed at "README" for named-path semantics now point at docs/scanning.md.

Configuration, CI, prior art, and license are unchanged, apart from cutting the version-cmd detail that docs/versions.md already covers.

Lead with a one-line pitch and a real three-trigger example, then
install and usage. Trigger syntax tables now live only in docs/,
scan rules move to docs/scanning.md, and the pipefail note moves to
docs/ci.md.
@alies-dev alies-dev self-assigned this Oct 20, 2026
@alies-dev
alies-dev requested a balanced review from Copilot October 20, 2026 23:50

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@coderabbitai

coderabbitai Bot commented Oct 20, 2026

Copy link
Copy Markdown

Review in Change Stack →

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 0d6d1cd5-7934-49e9-a975-35bc5cc8c07f
📥 Commits

Reviewing files that changed from the base of the PR and between 4cee072 and 1fc3804.

📒 Files selected for processing: 5
  • README.md
  • docs/ci.md
  • docs/scanning.md
  • src/main.rs
  • tests/overlapping_roots.rs
+---------------------------------------+
| r/CodeReview: Where I'm the top post. |
+---------------------------------------+
  \
   \   (\__/)
       (•ㅅ•)
       /   づ
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown
Contributor

🐰 Bencher Report

Projecttodo-by
Branchdocs-readme-ten-second-skim
Testbedubuntu-latest
Click to view all benchmark results
BenchmarkLatencyBenchmark Result
milliseconds (ms)
(Result Δ%)
Upper Boundary
milliseconds (ms)
(Limit %)
scan angular/angular📈 view plot
🚷 view threshold
135.45 ms
(+10.16%)Baseline: 122.96 ms
153.70 ms
(88.13%)
🐰 View full continuous benchmarking report in Bencher

@alies-dev
alies-dev merged commit 94fa472 into main Oct 20, 2026
16 of 17 checks passed
@alies-dev
alies-dev deleted the docs-readme-ten-second-skim branch October 20, 2026 23:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants