Preact: Add TODOs Badge to README

[patrickdevivo]

Hi there! I wanted to propose adding the following badge to the README to indicate how many TODO comments are in this codebase:

The badge links to tickgit.com which is a free service that indexes and displays TODO comments in public github repos. It can help surface latent work and be a way for contributors to find areas of code to improve, that might not be otherwise documented.

The markdown is:

[![TODOs](https://badgen.net/https/api.tickgit.com/badgen/github.com/preactjs/preact)](https://www.tickgit.com/browse?repo=github.com/preactjs/preact)

Thanks for considering, feel free to close this issue if it's not appropriate or you prefer not to!

[marvinhagemeister]

That's an excellent service and I can see how it can be useful for a few projects. I'm not sure if Preact falls into that category.

Just grepped our code for any todo comments and all except two very minor ones are exclusive to some nits/browser bugs in tests. Not sure what the other members think, but I'm worried that contributors will end up optimizing for the wrong metric. I could see them hesitate to add todo comments for the sake of keeping the number in this badge low.

Let's see what the others think :+1:

[patrickdevivo]

Hi @marvinhagemeister that's a very fair point and something I've noticed as a reaction to the TODOs badge in other repos as well (also, full disclosure I am the creator/maintainer of tickgit). Many Github badges are used to indicate the "health" of a codebase in some way (code coverage, "report card," etc) while others are more of a status indicator (# of downloads, forks, etc).

I don't think the TODOs badge should be interpreted as a metric for health, as you say, and I'd hate for it to mis-convey something about the state of a codebase. I had hoped using the blue color in the badge (as opposed to a yellow/red/green) would be a subtle way to communicate this "neutrality" (though the badge does turn green when there are 0 TODOs).

Maybe a potential badge to indicate "health" of a repo could be the average age of TODOs in a codebase (e.g. turn red if most TODOs are really old/unaddressed)

Anyways, I hope that context helps! I'm really happy you enjoy the service regardless of whether it makes sense to include the badge in preact! Thanks for the awesomeness of preact!

[ForsakenHarmony]

While I do see some value in having an overview of the TODOs (and FIXITs, ...), I don't think a badge gives much

Seems like a metric for maintainers, not the general public

[developit]

FWIW I really like the idea of having a tool for _finding_ our open TODOs, but I don't think we would want to use the badge. We actually are likely cutting down on the number of repo badges, since currently there's a fair bit of noise.

@patrickdevivo I'm assuming you run tickgit.com - any chance you're considering setting up a GitHub Action to bot that could highlight todos that are added/removed in PRs? I think we'd probably be interested in that more than the badge.

FWIW I just got a chance to peek at the tickgit linked from our badge and I have to say, this is a very useful service. Badge stuff aside, thanks for building something like this!

[marvinhagemeister]

Ohh a GitHub action sounds awesome 👍

[patrickdevivo]

@developit thanks for taking a peek and I'm glad you find it useful! I understand re: the badge and I think the Github Action proposal makes a lot of sense. It's something I've been thinking about on the backburner. https://github.com/augmentable-dev/tickgit is the tool doing the searching/indexing and the CLI could probably be turned into a very simple Action without too much work. I think where a lot of improvement could be made are in the knobs that could be added for various configuration preferences:

• Fail CI if X number of TODOs exist in the codebase (or maybe X TODOs per file/LOC?)?
• Fail if a PR introduces more TODOs than it removes?
• Fail/alert on TODOs that surpass an age threshold (i.e. remind me about this TODO in 1 month)
• Report the difference in TODOs of a PR (X were added, Y were removed)

And have the above apply to various code comment markers like FIXME, HACK, XXX, PERF, FIXIT etc., maybe with different rules/

Every project/developer seems to handle their TODOs a bit differently (some hate them, some are more rigorous about them - i.e. each one has an assignee).

I'll keep mulling it over and report back when some progress has been made! Thanks for considering and checking out the project, I really appreciate all the discussion/input. If there are other ways I can make it useful, please feel free to reach out! If it would be useful to link to the project for maintainers/contributors in another place, please let me know!

[marvinhagemeister]

Looks like the majority of the team voted against having a badge for TODOs in the README. We just switched our CI setup completely over to GitHub actions, so adding something there seems to be the best way forward for our project :+1:

Closing as there isn't an actionable thing to do here on our end.