Skip to content

Add iterative task handling - #4210

Open
carmiac wants to merge 6 commits into
GothenburgBitFactory:developfrom
carmiac:iterative_feature
Open

carmiac wants to merge 6 commits into
GothenburgBitFactory:developfrom
carmiac:iterative_feature

Conversation

@carmiac

@carmiac carmiac commented Oct 19, 2026

Copy link
Copy Markdown
Contributor

Add support for TaskChampion's iterative tasks.

  • Add iter and iter_type as built-in UDAs
  • Add a read-only iter_count column so it is not treated as an orphan and shows up in info
  • Reset iter_count on duplicate so the copy starts a new series
  • Add the ITERATIVE virtual tag, include iterative tasks in PENDING, and add an Iterative row to stats
  • Document iter and iter_type in task(1)

This currently uses a TC hash rather than version tag, since there isn't a release with it yet.

Add support for TaskChampion's iterative tasks.

- Add iter and iter_type as built-in UDAs
- Add a read-only iter_count column so it is not treated as an orphan
and shows up in info
- Reset iter_count on duplicate so the copy starts a new series
- Add the ITERATIVE virtual tag, include iterative tasks in PENDING, and
add an Iterative row to stats
- Add Task::is_open() and Task::is_pending() instead of the various
pending/waiting checks so that all the reports just work
- Document iter and iter_type in task(1)
- Bump the tc_cpp_test to accept the new rusqlite messages

This currently uses a TC hash rather than version tag, since there isn't
a release with it yet.
@carmiac
carmiac marked this pull request as ready for review October 19, 2026 18:45
Comment thread doc/man/task.1.in Resolved
Comment thread doc/man/task.1.in

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open question for now -- should iterative tasks be labeled as "experimental" at first?

If so, we'd also want to clarify what we mean by that. For example, we might be able to promise that the database will have a migration path forward without promising that the cli will not change.

Comment thread src/Task.cpp Resolved
Comment thread src/Task.cpp Resolved
Comment thread src/Task.cpp Resolved
Comment thread src/commands/CmdStats.cpp Resolved
Comment thread src/Context.cpp Resolved
Comment thread doc/man/task-iterative.5.in Resolved
Comment thread doc/man/task-iterative.5.in Resolved
Comment thread doc/man/task-iterative.5.in Resolved
Comment thread doc/man/task-iterative.5.in Resolved
Comment thread doc/man/task-iterative.5.in Resolved
Comment thread src/commands/CmdInfo.cpp Resolved
Comment thread src/columns/ColIterCount.cpp Resolved
@ryneeverett

Copy link
Copy Markdown
Collaborator

I was curious what would happen if you modify status:pending an iterative task. There is no error and the status reverts right back to iterative. That isn't terrible behavior but maybe it would be more user friendly to error?

Comment thread doc/man/task-iterative.5.in Resolved
Co-authored-by: ryneeverett <ryneeverett@gmail.com>
@ryneeverett

Copy link
Copy Markdown
Collaborator

I was curious what would happen if you modify status:pending an iterative task. There is no error and the status reverts right back to iterative. That isn't terrible behavior but maybe it would be more user friendly to error?

At this point this is my last remaining comment though it may have been missed since it wasn't in a review. Feel free to resolve all the review comments -- I believe I can't without repository write access.

@carmiac

carmiac commented Oct 27, 2026

Copy link
Copy Markdown
Contributor Author

Nice catch. I think there are two reasonable options, either it could error, or it could actually make it just a normal pending task. I'm not sure which one is more user friendly. What do you think?

@ryneeverett

Copy link
Copy Markdown
Collaborator

My weakly held opinion is that an error suggesting they clear iter: instead would be more appropriate. My thinking is:

  1. There are already 2 ways -- deleting and clearing iter: -- to manually end a series and making it a pending task would add a third which would be functionally identical to clearing iter:.
  2. Iterative tasks are often treated as pending tasks and users might not remain cognizant that they have a different status.
  3. Modifying status seems like a casual operation that only affects reports, whereas modifying iter always affects behavior.

Comment thread src/commands/CmdModify.cpp Outdated
Comment on lines +134 to +135
if (before.getStatus() == Task::iterative && after.get("iter") != "" &&
Task::textToStatus(after.get("status")) == Task::pending)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be applicable regardless of the status they try to set so maybe the last condition should be after.getStatus() != Task::iterative. That's what the error message implies anyway.

Comment thread doc/man/task-iterative.5.in Outdated

.RE
While a task is iterative, iter_type cannot be removed, the last of due,
scheduled and wait cannot be removed, and its status cannot be set to pending.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
scheduled and wait cannot be removed, and its status cannot be set to pending.
scheduled and wait cannot be removed, and its status cannot be modified.

@ryneeverett ryneeverett left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In terms of strategy, I'd suggest labeling this feature as experimental wherever is appears in the docs and releasing it. The upside of this approach is that we can make UI or behavior changes in subsequent minor versions without violating stability expectations. The downside is that communicating the meaning of "experimental" is a bit delicate:

  • the data is stable -- we're not going to change the format without a migration
  • it isn't provisional -- we're not going to delete the feature altogether
  • UI and behavior are subject to change -- therefore we're free to adapt to user feedback

Something like:

Experimental: UI and behavior of iterative tasks are subject to change in minor versions based on user feedback. However, the database format is stable and we're confident this will replace the recurrence system in a future release.

@ryneeverett ryneeverett mentioned this pull request Nov 7, 2026
1 of 11 tasks
@ryneeverett

Copy link
Copy Markdown
Collaborator

The pre-commit formatting check failure seems legitimate.

@djmitche

djmitche commented Nov 8, 2026

Copy link
Copy Markdown
Member

Agreed regarding the "experimental" annotation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants