St2: Add TODOs 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/StackStorm/st2)](https://www.tickgit.com/browse?repo=github.com/StackStorm/st2)

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

[armab]

Thanks for the proposal!

We're trying to direct our potential contributors in other direction showing where they can help first:
https://github.com/StackStorm/st2/blob/master/GOVERNANCE.md#how-to-start-contributing with good first issues (https://github.com/StackStorm/st2/contribute) and other areas.

The useful part of TODO comment metric looks low, comparing to noise level it adds to the list of existing st2 status badges. IMO TODO comments in our codebase could be outdated and expecting deeper level of understanding the code.

Curious what others think about this badge/metric? @StackStorm/tsc

[nmaludy]

I agree with @armab not super interested in this badge, not sure it adds much value.

[patrickdevivo]

@armab @nmaludy Thanks for the note and for considering! I agree that in general, the count of TODOs in a repo is not a very meaningful metric without further context (maybe total lines of code? files? TODOs per line of code/file? or per lines of comments vs "actual" code? etc). As such, I don't think the badge should be seen as a means of evaluating the health of a project, but understand how that might be ambiguous as many badges on Github _do_ intend to convey that (code coverage, open issues/PRs, "health report cards" etc). I was hoping the badge being blue might help convey that "neutrality".

My hope with the tickgit project is to make it easier for developers to return to their TODOs, as one thing that seems fairly common across codebases is our knack for forgetting about them once they're in the code (aside from those projects that seem to use TODOs as a way of explicitly tracking tickets).

I think as you point out, 1) the README is already a bit crowded with badges and 2) the TODOs index may not be a good place to direct new contributors.

Perhaps the TODO browser has value to existing contributors? Whether or not they are able to reach it via a badge in the README.

Some additional features I hope to add are:

• More advanced filtering (find by author/"last toucher", file path)
• More phrases (FIXME, HACK, XXX, etc)
• Text search
• Better parsing (markdown support + extracting URLs)

I fully understand if you feel the badge is not for this project! I hope tickgit was at least interesting to see! Feel free to let me know if there are any ways I can make it more useful for you! Thank you for your time regardess

[punkrokk]

What would be much more interesting to me would be a GH query that returns a search for all the “good first issues” in an org or repo and returned that search

I dont think I realized until now you were the author of the todo button. I think it’s a little forward to open issues suggesting the use of this service. Imagine if github opened an issue in every repo suggesting the use of one of their services. While it’s not the most unuseful thing ever, general use of todo in my experience is definitely internal. I kinda feel like this badge actually promotes the use of hard to find todos that encourage a questionable practice when GH Labels work great for a properly curated project. There are even bots that will do this.

On Feb 18, 2020, at 6:18 PM, Patrick DeVivo [e-mail] wrote:

@armab @nmaludy Thanks for the note and for considering! I agree that in general, the count of TODOs in a repo is not a very meaningful metric without further context (maybe total lines of code? files? TODOs per line of code/file? or per lines of comments vs "actual" code? etc). As such, I don't think the badge should be seen as a means of evaluating the health of a project, but understand how that might be ambiguous as many badges on Github do intend to convey that (code coverage, open issues/PRs, "health report cards" etc). I was hoping the badge being blue might help convey that "neutrality".

My hope with the tickgit project is to make it easier for developers to return to their TODOs, as one thing that seems fairly common across codebases is our knack for forgetting about them once they're in the code (aside from those projects that seem to use TODOs as a way of explicitly tracking tickets).

I think as you point out, 1) the README is already a bit crowded with badges and 2) the TODOs index may not be a good place to direct new contributors.

Perhaps the TODO browser has value to existing contributors? Whether or not they are able to reach it via a badge in the README.

Some additional features I hope to add are:

More advanced filtering (find by author/"last toucher", file path)
More phrases (FIXME, HACK, XXX, etc)
Text search
Better parsing (markdown support + extracting URLs)
I fully understand if you feel the badge is not for this project! I hope tickgit was at least interesting to see! Feel free to let me know if there are any ways I can make it more useful for you! Thank you for your time regardess

—
You are receiving this because you are on a team that was mentioned.
Reply to this email directly, view it on GitHub, or unsubscribe.

[punkrokk]

I’m closing this, if anyone wants to reopen because you think I’m off base feel free.

[patrickdevivo]

I dont think I realized until now you were the author of the todo button. I think it’s a little forward to open issues suggesting the use of this service. Imagine if github opened an issue in every repo suggesting the use of one of their services. While it’s not the most unuseful thing ever, general use of todo in my experience is definitely internal. I kinda feel like this badge actually promotes the use of hard to find todos that encourage a questionable practice when GH Labels work great for a properly curated project. There are even bots that will do this.

I'm sorry I didn't make it more clear I'm also the creator of the project. I also apologize opening issues on public repos I'm not typically involved in doesn't "taste right" - I know it could seem a bit spammy/self-serving. I promise my intentions are genuine though, in that though I am promoting a personal project, I do hope it has value to other developers/maintainers. I'm just trying to get it in front of folks who might find value in it and be willing to provide feedback!

I of course have no problem with your decision to ignore/close the issue. Thanks again for your time

[punkrokk]

Thanks for that @patrickdevivo

[patrickdevivo]

What would be much more interesting to me would be a GH query that returns a search for all the “good first issues” in an org or repo and returned that search

It won't show a count, but you could construct a badge with badgen like so:

[patrickdevivo]

Actually! Looks like you can:

[![Good First Issues](https://badgen.net/github/label-issues/StackStorm/st2/good%20first%20issue/open)](https://github.com/StackStorm/st2/labels/good%20first%20issue)

I think colors can be overridden, see https://badgen.net/