kkoyung commented 5 months ago

Description

TL;DR

Old mappings:

TW annotations, uuid <-> DESCRIPTION

New mappings:

TW uuid <-> X-SYNCALL-TW-UUID
TW annotations <-> DESCRIPTION (each annotation <-> a line in description)

Old mappings

If I understand the code correctly, the previous implementation uses the field DESCRIPTION of caldav to store meta-data of TW items.

When a TW item is converted to caldav item, the annotations and uuid of TW item are encoded into the following format, and stored in DESCRIPTION of caldav.

IMPORTED FROM TASKWARRIOR

* Annotation 1: first annotation
* Annotation 2: second annotation
* Annotation 3: third annotation
* uuid: 12345678-123-1234-1234-1234567890ab

When a caldav item is converted to TW item, syncall will try to parse the DESCRIPTION field of caldav item from the above format to get back the annotation and uuid. If lines not starting with * Annotation or * uuid will be ignored.

Problems of the old mappings

It makes the DESCRIPTION field of caldav unusable.

When user creates a task with description on caldav side, the description will be ignored by syncall and never reached taskwarrior. (Related issue: #72)

Some caldav application like Apple Reminder shows the description right below the task summary. The meta-data in DESCRIPTION takes up a lot of screen space, and make the task list bloat.

New mappings

In this new mappings, the uuid of TW item will be mapped to a non-standard iCalendar field X-SYNCALL-TW-UUID, allowed by RFC 5545. The annotation of TW item will be mapped to DESCRIPTION of caldav item. Each line in DESCRIPTION is corresponding to an annotation.

Remark

To avoid messing up the existing items with old mapping, syncall will try to parse the description as old mapping does, but any new synchronization will use the new mapping.
Lines in DESCRIPTION in caldav may be re-ordered after modifying the text and synchonizing. It is because the annotations in TW are sorted by the modified timestamp.
This patch works fine for my simple daily use, but I didn't test many edge cases.

Type of change

Please delete options that are not relevant.

[ ] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[x] Breaking change (fix or feature that would cause existing functionality to not work as expected)
[ ] This change requires a documentation update

How Has This Been Tested?

Updated the test samples in test/test_data/sample_items.yaml, and ran the tests.

Checklist:

[x] My code follows the style guidelines of this project
[x] I have commented my code, particularly in hard-to-understand areas
[x] I have made corresponding changes to the documentation
[x] My changes generate no new warnings
[x] I have added tests that prove my fix is effective or that my feature works
[x] Any dependent changes have been merged and published in downstream modules

Edit: forgot to embed the screenshot

bergercookie commented 1 month ago

This looks great! Will test it further before creating a new release but overall great work! Please keep the contributions coming @kkoyung :) :)

kkoyung commented 1 month ago