Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ with Workspace([Backend.open(tempfile.mkdtemp())]) as workspace:

I've been the maintainer of the Python CalDAV client package for many years now. The ironic thing is that I started using the library because I "didn't want to get my hands dirty". I had to do some fixes for the library to work towards my server, and soon enough the owner of the project passed me the maintainer hat. To be honest, I think neither the CalDAV protocol nor the iCalendar format is a particularly good standard. They are sort of the only open standards we have, so it's important to support them, but it's also important to support new and emerging standards.

There are no good standards for tasks. Apart from iCalendar, which supports task lists but not very well, there are only vendor formats. For instance, iCalendar has no way to record a time estimate or the time spent on a task. The estimate is about to be fixed (`ESTIMATED-DURATION` in the [task extensions draft](https://datatracker.ietf.org/doc/draft-ietf-calext-ical-tasks/), now in the RFC Editor queue), but time spent is still a gap. See [the task model survey](docs/design/TASK_MODEL_SURVEY.md).
There are no good standards for tasks. Apart from iCalendar, which supports task lists but not very well, there are only vendor formats. For instance, iCalendar has no way to record a time estimate or the time spent on a task. The estimate was fixed in October 2026 (`ESTIMATED-DURATION` in [RFC 10051](https://datatracker.ietf.org/doc/html/rfc10051)), but time spent is still a gap. See [the task model survey](docs/design/TASK_MODEL_SURVEY.md).

## Mission statement

Expand Down Expand Up @@ -79,7 +79,7 @@ Wanted, but outside the funded scope:
## Standards

* iCalendar - RFC 5545, with RFC 7986 (new properties) and RFC 9253 (relationships)
* The iCalendar task extensions draft (`ESTIMATED-DURATION`)
* The iCalendar task extensions - RFC 10051 (`ESTIMATED-DURATION`)
* CalDAV - RFC 4791, through `caldav`
* JMAP - RFC 8620 and JMAP Calendars, through `calendaring-jmap`
* vdir, for local file storage
Expand Down
48 changes: 30 additions & 18 deletions docs/design/API_DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ caller can lower that to a warning or allow it. Emulation is used only when
the result is the same or the weaker guarantee is documented (an emulated
conditional write can race), and `verify=True` reads a write
back to check it (**A5**, [§5.3](#53-what-happens-when-the-caller-asks-for-something-unsupported)).
Fields iCalendar has no property for go to RFC 9253 or the tasks draft
Fields iCalendar has no property for go to RFC 9253 or RFC 10051
first, and `X-PYCAL-*` only as a last resort (**A9**,
[§3.6](#36-properties-with-no-standard-home)).

Expand Down Expand Up @@ -810,12 +810,12 @@ Incorporates [survey Part 4](TASK_MODEL_SURVEY.md#part-4-a-proposed-task-model).

```python
class TaskStatus(StrEnum): # values are the iCalendar strings
PENDING = "PENDING" # tasks draft
PENDING = "PENDING" # RFC 10051
NEEDS_ACTION = "NEEDS-ACTION"
IN_PROCESS = "IN-PROCESS"
COMPLETED = "COMPLETED"
CANCELLED = "CANCELLED"
FAILED = "FAILED" # tasks draft
FAILED = "FAILED" # RFC 10051

class Task(Item): # component is an icalendar.Todo
native_status: str | None # see "Native passthrough"; not in the iCalendar data
Expand All @@ -830,19 +830,21 @@ class Task(Item): # component is an icalendar.Todo
Everything else is a property of the `VTODO`, read and written through
`component`. `TaskStatus` is the vocabulary backends map `STATUS` to and
from. It is not a field: `icalendar.enums.STATUS` has no `PENDING` or
`FAILED`, which the tasks draft adds, so those two are a candidate for
`icalendar` too. `set_duration()` is a method rather than a property
`FAILED`, which RFC 10051 adds, so those two are a candidate for
`icalendar` too ([issue 2055](https://github.com/collective/icalendar/issues/2055)). Until then `component.status` raises `ValueError` on them,
and `component.get("STATUS")` is the way to read them. `set_duration()` is a method rather than a property
because it changes two of them.

Decisions in it, each from the survey:

- **`DTSTART` means earliest sensible start.** That is the tasks draft's
reading and the first in the survey's table; the other senses the survey
- **`DTSTART` means earliest sensible start.** That is RFC 10051's
reading (§5.1) and the first in the survey's table; the other senses the survey
found (planned start, expected completion) get their own properties instead
of overloading it. Actual start comes from the time log ([roadmap 1.6](ROADMAP.md#16-time-tracking-model-and-api)), not from a field.
- **`duration` is derived, not stored.** On a task, `DURATION` is either
`DUE − DTSTART` or a misused estimate. `icalendar`'s `Todo.duration`
reads `DUE − DTSTART` (or `DURATION` when only that is present), and
- **`duration` is derived, not stored.** On a task with a `DTSTART`, `DURATION` is
either `DUE − DTSTART` or a misused estimate. `icalendar`'s `Todo.duration`
reads `DUE − DTSTART` (or `DURATION` when only that is present, which
RFC 10051 §11.1 makes legal), and
`task.set_duration(d, keep="due" | "start")` moves the other end, as
caldav's `set_duration(movable_attr=…)` does; plann uses both. The
default keeps `DUE`, as caldav's does, because a deadline is more often
Expand All @@ -856,11 +858,20 @@ Decisions in it, each from the survey:
- **`priority` is iCalendar's 0–9.** The survey found five incompatible
scales; the mapping to each is the backend's, documented as lossy.
plann's semantics for 1–9 sit on top of this and are plann's.
- **Whether `FAILED` is final is left open**, because RFC 10051 is very
unclear on it. §9.1 defines `PARTSTAT=FAILED` as "To-do cannot be
completed", but that is the participant's status. §11.2 says a task with
`STATUS:FAILED` "may need some follow-up" from the Organizer "to reschedule
or cancel", and Appendix A.3 ends its lifecycle on `FAILED`. So the library
is not consistent yet: `summarize()` counts no estimate for such a task and
a two-state tracker stores it as `COMPLETED`, while `include_completed=False`
still returns it, as `icalendar-searcher` excludes only `COMPLETED` and
`CANCELLED`. Full support of RFC 10051 is not on the roadmap.
- **Assignees are the task's `ATTENDEE`s** (`component.attendees`), as on
any other component. The tasks draft (section 6) says it in so
many words: "Tasks are assigned to actors using one or more RFC5545
'ATTENDEE' properties and/or one or more RFC9073 'PARTICIPANT'
calendar components." So the standard has no gap here, and no `X-`
any other component. RFC 10051 (section 6) says it in so
many words: "Tasks are assigned to actors using one or more 'ATTENDEE'
properties [RFC5545] and/or one or more 'PARTICIPANT' calendar
components [RFC9073]". So the standard has no gap here, and no `X-`
property is needed. What looks like a gap is that a tracker knows a
login (`alice`), while `ATTENDEE` takes a calendar address. A calendar
address is any URI, not only `mailto:` (RFC 5545 §3.3.3), so the Gitea
Expand Down Expand Up @@ -951,8 +962,8 @@ END:VEVENT
- **Who did the work is a `PARTICIPANT`, never an `ATTENDEE`.** RFC 9073
§7.1.1 makes a participant schedulable only when its
`CALENDAR-ADDRESS` matches an `ATTENDEE`. With none, no server sends
invitations, which an `ATTENDEE` would make it do (RFC 6638). The
tasks draft (§6) assigns with the same component. An entry may name
invitations, which an `ATTENDEE` would make it do (RFC 6638).
RFC 10051 (§6) assigns with the same component. An entry may name
several people; one duration then applies to each. Two people who
spent different times log two entries.
- **`X-PYCAL-TIME-ENTRY` marks it**, so the entry is recognised in any
Expand Down Expand Up @@ -989,7 +1000,8 @@ END:VEVENT
**For `sum_hours`**, `calendaring.timetracking.summarize(pairs, group_by=…,
window=(start, end))` groups `(item, entries)` pairs into
`TimeSummary(estimate, spent)` per key. `estimate` is the
`ESTIMATED-DURATION` of the open tasks, and `spent` the logged time. The
`ESTIMATED-DURATION` of the open tasks (not `COMPLETED`, `CANCELLED` or
`FAILED`), and `spent` the logged time. The
two are kept apart, since committed and spent time answer different
questions. The window clips entries, prorating one that straddles an
edge; an entry with no start counts by when it was logged.
Expand Down Expand Up @@ -1020,7 +1032,7 @@ and are not part of the model.

### 3.6 Properties with no standard home

[D6](PRIOR_ART_AND_DECISIONS.md#d6-canonical-in-memory-model) sets the order: an RFC 5545 property; then RFC 9253 or the tasks draft;
[D6](PRIOR_ART_AND_DECISIONS.md#d6-canonical-in-memory-model) sets the order: an RFC 5545 property; then RFC 9253 or RFC 10051;
then an `X-` property under one documented prefix. **The prefix is
`X-PYCAL-`**, after the project's name, [pycal.org](https://pycal.org)
(the GitHub organisation is `pycalendar` only because `pycal` was taken),
Expand Down
10 changes: 5 additions & 5 deletions docs/design/PRIOR_ART_AND_DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ The status of each standard was checked on the IETF datatracker on 2026-09-24.
| RFC 5545 iCalendar | RFC | the canonical data model (D6) | **yes** |
| RFC 7986 new iCalendar properties | RFC | `NAME`, `COLOR`, **`REFRESH-INTERVAL`**, `SOURCE` — the feed backend (2.3) should follow `REFRESH-INTERVAL` | **yes**, read side |
| RFC 9253 relationships | RFC | `LINK`, `CONCEPT`, `REFID`, extended `RELTYPE` — task dependencies (0.1) | **yes** |
| draft-ietf-calext-ical-tasks-17 | RFC Editor queue, "In Final Review" (2026-09-24) | `ESTIMATED-DURATION`, `VSTATUS`, new `STATUS` values — covered in the [task survey §1.2](TASK_MODEL_SURVEY.md) | **yes**, read + write `ESTIMATED-DURATION` |
| RFC 10051 task extensions | RFC (October 2026, checked 2026-11-01), updates RFC 5545 | `ESTIMATED-DURATION`, `VSTATUS`, new `STATUS` values — covered in the [task survey §1.2](TASK_MODEL_SURVEY.md) | **yes**, read + write `ESTIMATED-DURATION` |
| RFC 9074 VALARM extensions | RFC | acknowledge/snooze alarms | no — pass through untouched |
| RFC 9073 event publishing extensions | RFC | `PARTICIPANT`, `VLOCATION`, `STRUCTURED-DATA` | no — pass through untouched |
| RFC 7953 VAVAILABILITY | RFC | availability | no |
Expand All @@ -272,8 +272,8 @@ in the "beyond the funded scope" table. FEP-8a8e is the thing to build on, not
raw ActivityPub, because it exists precisely so that Mobilizon, Gancio and the
WordPress event plugins agree on what an `Event` looks like.

**A standards observation for 1.1:** of everything above, only iCalendar and the
tasks draft are needed to *model* the data. Every other entry is either a
**A standards observation for 1.1:** of everything above, only iCalendar and
RFC 10051 are needed to *model* the data. Every other entry is either a
transport (CalDAV, JMAP, HTTP, files) or something that must survive a round trip
untouched. The library's job for the latter is **not to lose them**. "Pass
through untouched" should be a conformance-suite test (1.2): read an object
Expand Down Expand Up @@ -541,7 +541,7 @@ The author's view is that `icalendar` is good enough, with one condition: the
[0.1 survey](TASK_MODEL_SURVEY.md) proposes fields that RFC 5545 has no
property for, extra timestamps among them. Those are stored as `X-`
properties. The order of preference, for 1.1 to apply field by field: an
RFC 5545 property; then one from RFC 9253 or the ical-tasks draft (Part 2);
RFC 5545 property; then one from RFC 9253 or RFC 10051 (Part 2);
then an `X-` property, under one documented prefix, so that a later standard
property can replace it without guessing.

Expand Down Expand Up @@ -600,7 +600,7 @@ caller-owned session that §1.4 asks for.
- Home Assistant core — https://github.com/home-assistant/core (components `caldav`, `todo`, `local_calendar`, `local_todo`, `remote_calendar`; `script/hassfest/quality_scale.py`)
- calendaring-jmap — https://github.com/pycalendar/calendaring-jmap
- pycal.org — https://github.com/pycalendar/pycal.org (`_data/packages.yml`)
- draft-ietf-calext-ical-tasks — https://datatracker.ietf.org/doc/draft-ietf-calext-ical-tasks/
- RFC 10051 — https://datatracker.ietf.org/doc/html/rfc10051
- draft-ietf-calext-jscalendarbis — https://datatracker.ietf.org/doc/draft-ietf-calext-jscalendarbis/
- draft-ietf-jmap-calendars — https://datatracker.ietf.org/doc/draft-ietf-jmap-calendars/
- draft-ietf-jmap-tasks — https://datatracker.ietf.org/doc/draft-ietf-jmap-tasks/
Expand Down
34 changes: 17 additions & 17 deletions docs/design/TASK_MODEL_SURVEY.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,22 +99,22 @@ plann's design notes, read it as the deadline; plann pins a task to the calendar
with a separate `VEVENT` linked through `RELATED-TO` instead of moving the task's
own timestamps.

The tasks draft (1.2) settles on the first reading. That was also plann's original
RFC 10051 (1.2) settles on the first reading. That was also plann's original
idea for `DTSTART`; it was abandoned only because the estimate needed somewhere to
live, which `ESTIMATED-DURATION` now provides.

### 1.2 The task extensions draft — the estimate gap is closing
### 1.2 RFC 10051, the task extensions — the estimate gap is closed

[`draft-ietf-calext-ical-tasks-17`](https://datatracker.ietf.org/doc/draft-ietf-calext-ical-tasks/)
("Task Extensions to iCalendar", Apthorp & Douglass, 10 December 2025) is a draft intended to become a Proposed Standard updating RFC 5545. It is at the RFC Editor, so it seems very likely that it will be published as an RFC within months. It focuses mostly on workflows involving multiple users. It adds granularity to task statuses, and it introduces a new property `ESTIMATED-DURATION`, which closes the estimate half of the README's gap.
[RFC 10051](https://datatracker.ietf.org/doc/html/rfc10051)
("Task Extensions to iCalendar", Apthorp & Douglass, October 2026) is a Standards Track RFC updating RFC 5545. This survey was written against draft -17; the changes in the published RFC are editorial. The RFC focuses mostly on workflows involving multiple users. It adds granularity to task statuses, and it introduces a new property `ESTIMATED-DURATION`, which closes the estimate half of the README's gap.

`ESTIMATED-DURATION` is the estimate, and `DTSTART` - `DUE` is the *window* a task may be performed in. The model in plann is to use `DURATION` as the estimate, and derive `DTSTART` from it.

It seems pretty obvious that we should support the tasks draft - time estimates should be embedded in `ESTIMATED-DURATION`, and `DURATION` should be the window for performing the task. This means icalendar task data created through plann has to be rewritten to support the tasks draft.
It seems pretty obvious that we should support RFC 10051 - time estimates should be embedded in `ESTIMATED-DURATION`, and `DURATION` should be the window for performing the task. This means icalendar task data created through plann has to be rewritten to support RFC 10051.

### 1.3 The time-spent gap is **not** closing

Neither the tasks draft nor JSCalendar defines anything for time actually spent. There is also no de-facto convention to be compatible with. Every known client that tracks time spent keeps it to itself, it's not exported to iCalendar format or to other systems. There are no known systems using X-properties for storing this information.
Neither RFC 10051 nor JSCalendar defines anything for time actually spent. There is also no de-facto convention to be compatible with. Every known client that tracks time spent keeps it to itself, it's not exported to iCalendar format or to other systems. There are no known systems using X-properties for storing this information.

A quick check of a handful of clients on 2026-09-24:

Expand All @@ -137,7 +137,7 @@ with his own assessment:
2. A new `PARTSTAT` value, `X-ATTENDED` — his current preferred workaround
3. A new component, `VTIMESPENT`

Note that candidate 2 gets more complicated when considering the tasks draft; it adds `PARTSTAT=FAILED` and a whole `VSTATUS` component in the same area of the spec.
Note that candidate 2 gets more complicated when considering RFC 10051; it adds `PARTSTAT=FAILED` and a whole `VSTATUS` component in the same area of the spec.

### 1.4 RFC 9253 — relationships are solved

Expand Down Expand Up @@ -172,10 +172,10 @@ to iCalendar.
Its `Task` object has those properties:

- **`estimatedDuration`** (`Duration`) — the estimate, as a first-class field, no
overloading of the window (§5.2.3) - mirrors the `ESTIMATED-DURATION` from the tasks draft
overloading of the window (§5.2.3) - mirrors the `ESTIMATED-DURATION` from RFC 10051
- **`percentComplete`** (`UnsignedInt`, 0–100) - as in RFC 5545
- **`progress`** (`String`) — `needs-action`, `in-process`, `completed`, `failed`,
`cancelled`, the tasks draft's values minus `PENDING`, but also extensible via the IANA "JSCalendar Enum Values" registry or a
`cancelled`, RFC 10051's values minus `PENDING`, but also extensible via the IANA "JSCalendar Enum Values" registry or a
vendor prefix (§5.2.5).
- **`progressUpdated`** (`UTCDateTime`) — when `progress` was last set (§5.2.6)
- **per-participant `progress` and `progressUpdated`**, with the task-level
Expand All @@ -189,7 +189,7 @@ Its `Task` object has those properties:

### 1.6 Differences

| Capability | RFC 5545 | + tasks draft | RFC 9253 | JSCalendar |
| Capability | RFC 5545 | + RFC 10051 | RFC 9253 | JSCalendar |
|---|---|---|---|---|
| Time estimate | overloaded onto `DURATION` | **`ESTIMATED-DURATION`** | — | **`estimatedDuration`** |
| Status | 4 values | 6 values + `VSTATUS` | — | 5 values, extensible |
Expand Down Expand Up @@ -795,17 +795,17 @@ declares the log unsupported and accepts writes of the aggregate.

- **Binary** — Gitea, GitLab (`open`/`closed`), Vikunja and Kanboard (a `done`
flag). Everything richer lives in labels or board columns.
- **Fixed small enum** — Taskwarrior (4), iCalendar/EteSync (4, or 6 with the
tasks draft), JSCalendar (5).
- **Fixed small enum** — Taskwarrior (4), iCalendar/EteSync (4, or 6 with
RFC 10051), JSCalendar (5).
- **Configurable** — org-mode keywords, Kanboard columns, OpenProject status
resources, RT queue lifecycles. RT alone also models the legal *transitions*.

**A normalised status enum is necessary and insufficient.** The
model needs both: a normalised value drawn from the tasks draft's six
model needs both: a normalised value drawn from RFC 10051's six
(`PENDING`, `NEEDS-ACTION`, `IN-PROCESS`, `COMPLETED`, `CANCELLED`, `FAILED`),
and the backend's **native status string preserved alongside it**, because
round-tripping a Kanboard card through a normalised enum would otherwise move
it to a different column. The tasks draft's six values are a good
it to a different column. RFC 10051's six values are a good
normalisation target precisely because they are the widest fixed vocabulary
anyone has standardised.

Expand Down Expand Up @@ -929,7 +929,7 @@ The `time_log` consists of TimeEntries that can be summed up to get the actual t
In addition extra timestamps may be applied:

* Creation time for the task
* Earliest possible start (`dtstart` in tasks draft)
* Earliest possible start (`dtstart` in RFC 10051)
* Expected start
* Expected completion
* Due
Expand Down Expand Up @@ -1054,8 +1054,8 @@ architecture, and belong with 2.2 rather than 2.5).
- [RFC 5545 — iCalendar](https://datatracker.ietf.org/doc/html/rfc5545)
- [RFC 8984 — JSCalendar](https://www.rfc-editor.org/rfc/rfc8984.txt)
- [RFC 9253 — Support for iCalendar Relationships](https://datatracker.ietf.org/doc/html/rfc9253)
- [draft-ietf-calext-ical-tasks-17 — Task Extensions to iCalendar](https://datatracker.ietf.org/doc/draft-ietf-calext-ical-tasks/)
([text of -17](https://www.ietf.org/archive/id/draft-ietf-calext-ical-tasks-17.txt))
- [RFC 10051 — Task Extensions to iCalendar](https://datatracker.ietf.org/doc/html/rfc10051)
(the survey was written against [draft -17](https://www.ietf.org/archive/id/draft-ietf-calext-ical-tasks-17.txt))

### Systems surveyed
- Gitea — [`modules/structs/issue.go`](https://github.com/go-gitea/gitea/blob/main/modules/structs/issue.go), [`issue_tracked_time.go`](https://github.com/go-gitea/gitea/blob/main/modules/structs/issue_tracked_time.go), [`issue_stopwatch.go`](https://github.com/go-gitea/gitea/blob/main/modules/structs/issue_stopwatch.go)
Expand Down
Loading
Loading