shopify / smart_todo

Enhance TODO comment in your Ruby code

SmartTodo is a library designed to assign users on TODO comments written in your codebase and help assignees be reminded when it's time to commit to their TODO.

Installation

1. Add the gem in your Gemfile.

group :development do
  gem 'smart_todo', require: false # No need to require it
end

2. Run bundle install

Summary

SmartTodo allows to write TODO comments alongside your code and assign a user to it. When the TODO's event is met (i.e. a certain date is reached), the TODO's assignee will get pinged on Slack.

Without SmartTodo

  # TODO: Warning! We need to change the API endpoint on July 1st because the provider
  # is modifying its API.
  def api_call
  end

---

With SmartTodo

  # TODO(on: date('2019-07-01'), to: '[email protected]')
  #   The API provider is modifying its endpoint, we need to modify our code.
  def api_call
  end

Documentation

Please check out the GitHub wiki for documentation and example on how to setup SmartTodo in your project.

License

This project is licensed under the terms of the MIT license. See the LICENSE file.

smart_todo's Issues

Add a `OnVersionBump` event

Find a way to generate a github link to the todo

Right now the slack message say in which file the TODO is, but doesn't tell in what project.
We should link provide a direct link to github

Does our assumption that todo comments are inlined hold in practice?

      # Check if the comment is associated with the Smart Todo
      # @param comment [String] the actual Ruby comment
      # @return [true, false]
      #
      # @example When a comment is associated to a SmartTodo
      #   TODO(on_date(...), to: '...')
      #     This is an associated comment
      #
      # @example When a comment is not associated to a SmartTodo
      #   TODO(on_date(...), to: '...')
      #   This is an associated comment (Note the indentation)

Codebases don't seem to always apply this rule, leading to empty todo comments being reported? Should we mention the rule in the message perhaps? Or relax the rule?

Support multiple file types

Hey, this gem is awesome! One thing we would love is the ability to use this on other filetypes, specifically typescript and scss. Is there currently a way to do this?

Gem release check is failing with HTTP timeout

We have a step on CI that checks TODOs and it's failing with HTTP timeout quite often:

/usr/local/ruby/lib/ruby/3.0.0/net/protocol.rb:43:in `ssl_socket_connect': Net::OpenTimeout (Net::OpenTimeout)
--
  | from /usr/local/ruby/lib/ruby/3.0.0/net/http.rb:1038:in `connect'
  | from /usr/local/ruby/lib/ruby/3.0.0/net/http.rb:970:in `do_start'
  | from /usr/local/ruby/lib/ruby/3.0.0/net/http.rb:959:in `start'
  | from /usr/local/ruby/lib/ruby/3.0.0/net/http.rb:1512:in `request'
  | from /usr/local/ruby/lib/ruby/3.0.0/net/http.rb:1270:in `get'
  | from /tmp/bundle/ruby/3.0.0/gems/smart_todo-1.2.0/lib/smart_todo/events/gem_release.rb:28:in `met?'
  | from /tmp/bundle/ruby/3.0.0/gems/smart_todo-1.2.0/lib/smart_todo/events.rb:38:in `gem_release'

I haven't found any information regarding SLO for rubygems API. But I think it would be helpful to allow to configure HTTP client and maybe even use faraday instead of standard ruby HTTP client.

Here is the code for the reference:

https://github.com/Shopify/smart_todo/blob/master/lib/smart_todo/events/gem_release.rb#L63

Add an example in the wiki to demonstrate how to run on an array of paths

Hey!
I think it would be helpful to add an example like this in the CLI page. I was looking in how to add the Gemfile to the parsed paths.

ENABLE_SMART_TODO=1 bundle exec smart_todo Gemfile . --fallback_channel '#general' --slack_token 'abc'

Crash on # TODO?

The smart todo parser crashes when the comment contains # TODO?

To reproduce add the following test to smart_todo_cop_test.rb:

    def test_add_offense_when_todo_has_question_mark
      expect_offense(<<~RUBY)
      # TODO?
      RUBY
    end

Stacktrace:

NoMethodError: undefined method `[]' for #<SmartTodo::Parser::MethodNode:0x0000000126188518 @arguments=nil, @method_name="TODO?">
    /Users/martinwallace/src/github.com/Shopify/smart_todo/lib/smart_todo/parser/metadata_parser.rb:96:in `process'
    /Users/martinwallace/src/github.com/Shopify/smart_todo/lib/smart_todo/parser/metadata_parser.rb:24:in `block in parse'
    <internal:kernel>:90:in `tap'
    /Users/martinwallace/src/github.com/Shopify/smart_todo/lib/smart_todo/parser/metadata_parser.rb:24:in `parse'

Link to the line of the TODO in the notifications

Accept a repository config in the command line so we can generate a link to the TODO.

Support FIXME and OPTIMIZE tags

Those are common in Rails applications.

Bonus point to support any configurable tag.

Add a `OnOccasionaly` event

Useful when you don't really know when the todo comes to expiration but want to be reminded every so often

Support branch event

I'd like to be able to fire notifications when a TODO is merged into a specific branch. This is useful for things where you have to wait for something to be running in production before you can make more changes (e.g. backfills).

The way I think this could work is to have a branch: 'production' option, and all that would do is check "does the currently checked-out branch match the given branch name?". It could potentially support RegExp as well for more advanced matching.

Since this requires running smart_todo across multiple branches, it would also be nice to support an --events flag to filter which events actually get checked. So in this case, I would run smart_todo normally in our main branch, and then smart_todo --events branch in the production branch when a new release is pushed.

So this is kind of two features in one. I'd like to know:

1. Is this repo open to contributions for events that Shopify might not use?
2. Do these features sound reasonable to add?

Enforce smart_todo comment by providing a rubocop cop

Support running bin locally with no credentials

I have a CI failure due to smart_todo here: https://buildkite.com/shopify/dev/builds/13584#8c3ee7ca-e462-4f27-a38a-b6d951a562af

In order to debug this, the first thing I tried is to run bin/smart_todo locally, but it won't let me.

It would be really useful if it supported running locally without credentials, but just printing the triggered conditions.

Check for blank environment variables

I was pairing with @wildmaples to add this to our CI, and it was failing with:

read:0x00007f579f41cb18 /usr/local/bundle/ruby/3.2.0/gems/smart_todo-1.7.0/lib/smart_todo/cli.rb:121 run> terminated with exception (report_on_exception is true):
--
  | /usr/local/bundle/ruby/3.2.0/gems/smart_todo-1.7.0/lib/smart_todo/slack_client.rb:97:in `slack_response!': Response body: {"ok"=>false, "error"=>"not_authed"} (SmartTodo::SlackClient::Error)

It turned out we were setting SMART_TODO_SLACK_TOKEN, but it was evaluating to an empty string 🙊 . I think it's a simple adjustmen to check for it to be non-empty.

Add the `OnPullRequestClosed` and `OnIssueClosed` events

"TODO(username):" pattern

Was talking through this the other day with the rest of the team. It sounds like smart_todo will try to interpret all TODO(*) comments, and this would conflict with the common "TODO(me):" pattern.

If that's correct, I think this is kind of unreasonable, but I don't have a suggestion for how this could be handled differently.

Anyway, here's a place for discussion about this conflict.

sdhasdh

Asynchronous Interaction Resources

The JSA Program has been showing persistent performance concerns with async smiley since the channel has been introduced in the summer of 2023. Support advisors in Solstice have been greatly outperforming the JSA Program, and we need to create an action plan to increase the average quality of async interactions. Below are the commitments we made to help increase average async smiley in the JSA Program:

1. Create a list of stellar async interactions that our Junior Support Advisors can study
2. Focus our Q4 2023 homesite on how to bring Surprise & Delight to our async interactions
3. Curate a small collection of courses and resources that can help up-skill our Junior Support Advisors on async interactions

Crash when parsing quadruple pound

I commented out two methods with plain TODOs, like the following:

    # def change!
    #   return if already_changed?
    #   super # TODO: fix
    # end

    # def override_me(arg)
    #   super # TODO: fix
    #   self.arg_set = !!arg
    # end

This caused the smart-todo system to crash:

Traceback (most recent call last):
--
  | 15: [...]
  | 14: [...]
  | 13: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/exe/smart_todo:12:in `<top (required)>'
  | 12: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/cli.rb:20:in `run'
  | 11: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/cli.rb:20:in `each'
  | 10: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/cli.rb:21:in `block in run'
  | 9: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/cli.rb:21:in `each'
  | 8: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/cli.rb:22:in `block (2 levels) in run'
  | 7: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/cli.rb:70:in `parse_file'
  | 6: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/parser/comment_parser.rb:36:in `parse'
  | 5: [...]
  | 4: [...]
  | 3: [...]
  | 2: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/parser/comment_parser.rb:23:in `on_comment'
  | 1: from /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/parser/comment_parser.rb:61:in `todo_comment?'
  | /tmp/bundle/ruby/2.6.0/gems/smart_todo-1.1.0/lib/smart_todo/parser/todo_node.rb:39:in `indented_comment?': undefined method `[]' for nil:NilClass (NoMethodError)

Implement plugins for assigment

Today, if the assignment of a TODO is invalid, we just send to a single fallback channel.

It would be ideal if we could configure some code that could try to find the owner of a TODO based on the path of the file where the TODO is defined.

As this logic would depend from codebase to codebase, this can't be static.