Updating a TODO

The Catana dashboard doesn't have an "Edit TODO" button. But no worries, you can still update a TODO!

This page will explain some of Catana's internals and how it detects new versus updated TODO when you push code changes.

Source of truth

A common problem with TODOs coupled with an Issue tracker is that over time their information diverges. The Issue is closed, but the TODO remains in your code (or the other way around). A TODO is assigned to Bob, but Bob no longer works here. Catana addresses this problem by making your repository the source of truth.

To update a TODO: the code in the codebase has to be changed.

Data source

Catana pulls its data from "git diffs". A Git Diff consists of addition lines and deletion lines. When a TODO is updated, Catana parses a diff similar to this:

diff --git a/some_file.rb b/some_file.rb
index e0252e6..fee4d68 100644
--- a/some_file.rb
+++ b/some_file.rb
@@ -9,3 +9,3 @@ class SomeFile
-  # TODO(on: date("2021-01-01"), to: "bob")
+  # TODO(on: date("2021-01-18"), to: "roger")
   def write
     @content.write
   end

It's ambiguous for Catana. Should a new TODO be created and the old one deleted, or should we update it?

To differentiate, Catana uses the conventions outlined below.

Conventions

Same line number

Catana considers a TODO to be updated if the new TODO is on the same line number as the previous one.

diff --git a/some_file.rb b/some_file.rb
index e0252e6..fee4d68 100644
--- a/some_file.rb
+++ b/some_file.rb
@@ -9,3 +9,3 @@ class SomeFile
-  # TODO(on: date("2021-01-01"), to: "bob")
+  # TODO(on: date("2021-01-18"), to: "roger")
   def write
     @content.write
   end

The TODO assigned to bob and expiring on January 1st in this example will be updated. The TODO will be assigned to Roger and will expire on January 18th.


diff --git a/some_file.rb b/some_file.rb
index e0252e6..fee4d68 100644
--- a/some_file.rb
+++ b/some_file.rb
@@ -9,3 +9,3 @@ class SomeFile
-  # TODO(on: date("2021-01-01"), to: "bob")
   def write
     @content.write
   end
+  # TODO(on: date("2021-01-18"), to: "roger")

The TODO assigned to bob and expiring on January 1st in this example will be deleted. A new TODO will be created and assigned to Roger. It will expire on January 18th.

Same title

The convention on the same line number doesn't apply if your TODO has a title. If two TODOs in the diff have the same title, Catana considers it an update.

diff --git a/some_file.rb b/some_file.rb
index e0252e6..fee4d68 100644
--- a/some_file.rb
+++ b/some_file.rb
@@ -9,3 +9,3 @@ class SomeFile
-   # TODO(on: date("2021-01-01"), to: "bob") Look into implementing `read`
-   def write
+   def write # TODO(on: date("2021-01-18"), to: "roger") Look into implementing `read`
     @content.write
   end

The title of both TODOs is the same ("Look into implementing read"). Catana considers this an update and will reflect the changes.

The TODO assigned to bob and expiring on January 1st in this example will be updated. The TODO will be assigned to Roger and will expire on January 18th.

Same event

Catana considers a TODO to be updated if and only if the new TODO has the same event as the old TODO. The arguments of the event can change, but not the event itself.

For instance, if you wanted to update a TODO to expire at an ulterior date:

diff --git a/some_file.rb b/some_file.rb
index e0252e6..fee4d68 100644
--- a/some_file.rb
+++ b/some_file.rb
@@ -9,3 +9,3 @@ class SomeFile
-  # TODO(on: date("2021-01-01"), to: "bob")
+  # TODO(on: date("2021-01-18"), to: "roger")
   def write
     @content.write
   end

The TODO assigned to bob and expiring on January 1st in this example will be updated. The TODO will be assigned to Roger and will expire on January 18th.


diff --git a/some_file.rb b/some_file.rb
index e0252e6..fee4d68 100644
--- a/some_file.rb
+++ b/some_file.rb
@@ -9,3 +9,3 @@ class SomeFile
-  # TODO(on: date("2021-01-01"), to: "bob")
+  # TODO(on: issue_close("python", "cpython", 7651), to: "bob")
   def write
     @content.write
   end

The TODO assigned to bob and expiring on January 1st in this example will be deleted. A new TODO will be created and assigned to Roger. It will expire when the Python/cpython GitHub Issue 7651 is closed.