Draft

This is a draft design document. Your feedback is welcomed.

Recurrence

Recurrence needs an overhaul to improve weaknesses and add new features.

Terminology

• The hidden ‘parent’ task is called the template.
• Synthesis is the name for the generation of new recurring task instances when necessary.
• The synthesized tasks are called instances.
• The index is the zero-based monotonically increasing number of the instance.
• Drift is the accumulated errors in time that cause a due date to slowly change for each recurring task.

Criticism of Current Implementation

• The mask attribute grows unbounded.
• Only strict recurrence cycles are supported. The example of mowing the lawn is that you want to mow the lawn every seven days, but when you are four days late mowing the lawn, the next mowing should be in seven days, not in three.
• Intances generated on one machine and then synced, may collide with equivalent unsynced instances tasks on another device, because the UUIDs are different.
• You cannot wait a recurring task and have that wait period propagate to all other child tasks.
• Task instances cannot individually expire.

Proposals

Proposal: Eliminate mask, imaѕk Attributes

The mask attribute in the template is replaced by last, which indicates the most recent instance index synthesized. Because instances are never synthesized out of order, we only need to store the most recent index. The imask attribute in the instance is no longer needed.

Proposal: Rename parent to template

The name parent implies subtasks, and confuses those who inspect the internals. The value remains the UUID of the template. This frees up the namespace for future use with subtasks.

Proposal: New ‘rtype’ attribute

To indicate the flavor of recurrence, support the following values:

• periodic - Instances are created on a regular schedule. Example: send birthday flowers. It must occur on a regular schedule, and doesn’t matter if you were late last year. This is the default value.

• chained - Instances are created back to back, so when one instance ends, the next begins, with the same recurrence. Example: mow the lawn. If you mow two days late, the next instance is not two days early to compensate.

Proposal: Use relative offsets

The delta between wait and due date in the template should be reflected in the delta between wait and due date in the instance. Similarly, ‘scheduled’ must be handled the same way.

Proposal: On load, auto-upgrade legacy tasks

Upgrade template:

• Add rtype:periodic
• Add last:N where N is the length of mask
• Delete mask

Upgrade instance:

• Rename parent to template
• Delete imask
• Update wait if not set to: wait:due + (template.due - template.wait)
• Update scheduled if not set to: scheduled:due + (template.due - template.scheduled)

Proposal: Deleting a chained instance

Deleting a rtype:chained instance causes the next chained instance to be synthesized. This gives the illusion that the due date is simply pushed out to (now + template.recur).

Proposal: Modification Propagation

TBD

Proposal: Exotic Dates

Expand date specifications to use pattern phrases:

• 4th thursday in November
• 4th thursday of November
• Friday before easter
• next Tuesday
• last Tuesday
• last July
• weekend
• 3 days before eom
• in the morning
• 4pm
• noon
• midnight

Got suggestions?

Proposal: User-Defined Week Start

TBD

Implementation

Implementation: Adding a new periodic template

When adding a new periodic template:

task add ... due:D recur:R wait:D-1wk scheduled:D-1wk until:U

Creates:

template.uuid:        NEW_UUID
template.description: ...
template.entry:       now
template.modified:    now
template.due:         D
template.recur:       R       (stored in raw form, ie 'P14D')
template.wait:        D-1wk
template.scheduled:   D-1wk
template.until:       U
template.rtype:       periodic
template.last:

Creating the Nth instance (index N):

Clone instance from template.

instance.uuid:        NEW_UUID
instance.modified:    now
instance.due:         template.due + (N * template.recur)
instance.wait:        instance.due + (template.due - template.wait)
instance.scheduled:   instance.due + (template.due - template.scheduled)
instance.start:

template.last:        N

Implementation: Adding a new chained template

When adding a new chained template:

task add ... due:D recur:R wait:D-1wk scheduled:D-1wk until:U rtype:chained

Creates:

template.uuid:        NEW_UUID
template.description: ...
template.entry:       now
template.modified:    now
template.due:         D
template.recur:       R       (stored in raw form, ie 'P14D')
template.wait:        D-1wk
template.scheduled:   D-1wk
template.until:       U
template.rtype:       chained

Creating the Nth instance (index N):

Clone instance from template.

instance.uui  d:        NEW_UUID
instance.mod  ified:    now
instance.due  :         instance[N-1].end + template.recur
instance.wai  t:        instance.due + (template.due - template.wait)
instance.sch  eduled:   instance.due + (template.due - template.scheduled)
instance.sta  rt:

Chained tasks do not obey rc.recurrence.limit, and show only one pending task at a time.

Implementation: Special handling for months

Certain recurrence periods are inexact:

• P1M
• P1Y
• P1D

When the recurrence period is P1M the number of days in a month varies and causes drift.

When the recurrence period is P1Y the number of days in a year varies and causes drift.

When the recurrence period is P1D the number of hours in a day varies due to daylight savings, and causes drift.

Drift should be avoided by carefully implementing:

instance.due: template.due + (N * template.recur)