summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGeorg C. F. Greve <greve@kolabsys.com>2010-12-06 18:12:08 (GMT)
committerGeorg C. F. Greve <greve@kolabsys.com>2010-12-06 18:12:08 (GMT)
commit5b8bd2f192f8aa695c78b4ab8250b3584501e458 (patch)
treeea0811f29d4a61d6c74801f7e986f0b3a91e8931
parentfe9bdbfecdfc11c3443199f5cdc3fa6e5f26f650 (diff)
downloadkeps-5b8bd2f192f8aa695c78b4ab8250b3584501e458.tar.gz
Some editorial restructuring, and further examples added
-rw-r--r--KEP-0002.txt34
1 files changed, 23 insertions, 11 deletions
diff --git a/KEP-0002.txt b/KEP-0002.txt
index 89fa41e..462aeb7 100644
--- a/KEP-0002.txt
+++ b/KEP-0002.txt
@@ -33,27 +33,39 @@ The type for datetime storage in Kolab XML is modified as follows:
* All such timestamps '''MUST''' be calculated against *Standard Time*, '''NOT''' in Daylight Saving Time (DST).
* All datetime storage fields '''MAY''' carry up to one 'tz' hierarchically nested sub-tag describing the time zone in the uniform naming convention designed by Paul Eggert, specifying time zones from the Olson database, a.k.a. tz database, a.k.a. zoneinfo database <ref>[[wikipedia:Zoneinfo | Wikipedia: Zoneinfo]]</ref>.
-Examples of valid 'start-date' fields using datetime structures according to the above specification are
+=== Canonical client behaviour ===
-* <start-date>2010-01-31T11:27:21Z</start-date> (a.k.a. "Zulu notation")
+When time zone information is provided, a client '''MUST''' consider the event local to this time zone. Recurrence '''MUST''' then be calculated to keep the event at the same local time within that time zone, adjusting the time for the event accordingly for the client's local time zone (see [#Notes_for_client_implementors] below for further information).
-* <start-date>2010-01-31T11:27:21+00:00</start-date>
+When no time zone information is provided, a client '''MUST''' calculate recurrences strictly according to UTC.
-* <start-date>1996-12-19T16:39:57-08:00</start-date>
+When modifying objects, clients '''MUST''' preserve the original time zone used for storage unless changed by user interaction.
-* <start-date>1996-12-19T16:39:57-08:00<tz>America/Sao_Paulo</tz></start-date>
+When adding new objects, clients '''SHOULD''' default to the local time zone of the user, but SHOULD allow the user to select the time zone for storage and consequently recurrence calculation.
-* <start-date>1985-04-12T23:20:50.52Z</start-date>
+=== Examples ===
-{{note|While only the first conforms with the specification document, the first two examples are identical to the datetime type used in Kolab XML storage by clients 'in the wild' prior to this modification.}}
+Examples of valid 'start-date' fields using datetime structures according to the above specification are
-When time zone information is provided, a client '''MUST''' consider the event local to this time zone. Recurrence '''MUST''' then be calculated to keep the event at the same local time within that time zone, adjusting the time for the event accordingly for the client's local time zone.
+* '''Authoritative structure''' (a.k.a. "Zulu notation"): Clients '''MUST''' write datetime for 'note', 'contact', 'distribution-list', 'journal', 'event' and 'task' objects without timezone information - the event was defined by the user as strictly ''sticky'' to UTC - in this markup:
-When no time zone information is provided, a client '''MUST''' calculate recurrences strictly according to UTC.
+ <start-date>2010-01-31T11:27:21Z</start-date>
-When modifying objects, clients '''MUST''' preserve the original time zone used for storage unless changed by user interaction.
+* Examples of some RFC3339 structures that parsers '''MUST''' also be able to parse correctly:
-When adding new objects, clients '''SHOULD''' default to the local time zone of the user, but SHOULD allow the user to select the time zone for storage and consequently recurrence calculation.
+ <start-date>2010-01-31T11:27:21+00:00</start-date>
+ <start-date>1996-12-19T16:39:57-08:00</start-date>
+ <start-date>1985-04-12T23:20:50.52Z</start-date>
+
+* With optional timezone component added to "Zulu notation", this is how clients '''MUST''' write 'note', 'contact', 'distribution-list', 'journal', 'event' and 'task' objects where the user specified the event should be ''sticky'' to a certain timezone:
+
+ <start-date>2010-01-31T11:27:21Z<tz>America/Sao_Paulo</tz></start-date>
+
+* With optional timezone component to RFC3339 string, clients '''MUST''' also be able to parse this correctly:
+
+ <start-date>1996-12-19T16:39:57-08:00<tz>America/Sao_Paulo</tz></start-date>
+
+{{note|While only the first conforms with the previous specification document, the first two examples are identical to the datetime type used in Kolab XML storage by clients 'in the wild' prior to this modification.}}
=== Upgrade Path ===