Syntax

Syntax

SmartTodo uses a syntax derived from the regular TODO comment in order to not break existing tools (IDE, code coverage ...)

# TODO(on: date('2019-01-18'), to: '[email protected]')
#   This is a comment associated with the TODO.

---

A SmartTodo starts with the keyword TODO followed by (), just like regular ruby method calls (in fact SmartTodo expects a valid ruby syntax). Inside the parenthesis, SmartTodo expects at least two keywords: on and to. An optional context keyword can also be added.

on

The on keyword is used to define the event associated with this TODO task. Events are what makes your TODO to expire and be reminded about it. SmartTodo has few built-in useful events, you can check out the list here.

You can define multiple events for your TODO. In such case, if any of the event is met, your TODO will be considered as expired. To define multiple events you simply have to add more on keywords.

# TODO(on: date('2019-01-18'), on: gem_release('rails', 'rails', 54251),  to: '[email protected]')
#   This is a comment associated with the TODO.

to

The to keyword is to assign a user to the TODO. It expects either the full email address of the Slack user, or a Slack channel. You can't provide the nickname of the Slack user.

# TODO(on: date('2019-01-18'), to: '[email protected]')
#   Associated comment

# TODO(on: date('2019-01-18'), to: '#general')
#   Associated comment

The to keyword can also be used multiple times in the same TODO to send notifications to multiple Slack channels or users:

# TODO(on: date('2019-01-18'), to: '[email protected]', to: '[email protected]', to: '#general')
#   Associated comment

context (optional)

The context keyword allows you to link your TODO to a GitHub issue, providing additional context when the TODO is triggered. This is particularly useful for tracking the relationship between code TODOs and their corresponding GitHub issues.

The context keyword expects a string in the format "org/repo#issue_number".

When to use context

The context attribute can be used with any event type to provide additional context:

• ✅ All events are supported: date, gem_release, gem_bump, ruby_version, issue_close, pull_request_close
• For issue_close and pull_request_close, the context typically references a different issue that describes related or follow-up work

Example with context

# TODO(on: date('2025-02-01'), to: '[email protected]', context: "shopify/smart_todo#108")
#   Implement the caching strategy discussed in the issue

# TODO(on: gem_release('rails', '> 7.2'), to: '[email protected]', context: "rails/rails#456")
#   Upgrade to new Rails version and implement features from the linked issue

# TODO(on: ruby_version('>= 3.3'), to: '[email protected]', context: "ruby/ruby#789")
#   Use the new Ruby syntax features as discussed in the issue

When a TODO with context is triggered, the notification will include:

• 📌 The issue title
• The issue state (open/closed)
• The assignee (if any)
• A direct link to the issue

This provides valuable context to whoever receives the notification, helping them understand not just what needs to be done, but why it needs to be done and what discussions led to this TODO.

Authentication for private repositories

If the linked issue is in a private repository, you'll need to expose a GitHub token with the repo scope, just like with the issue_close and pull_request_close events. The token should be exposed in the SMART_TODO_GITHUB_TOKEN environment variable.

Associated comment

It's not required but it's a good practice to add an associated comment as part of the TODO. It helps to get the context of why this TODO was written. The comment will be sent alongs the Slack message.

To add a comment as part of your TODO, it has to be indented 2 spaces below the TODO() declaration. You can add as many comment lines as you want as long as they are indented.

# TODO(on: date('2019-01-18'), to: '[email protected]')
#   Associated comment
#   Another comment
#   And another one ...