Repository navigation
Roadmap 1.6: time tracking - #25
Merged
Merged
Conversation
Time spent on a task or in a meeting is an append-only log of entries, stored as VEVENTs marked X-PYCAL-TIME-ENTRY, related to the task or event, with RFC 9073 PARTICIPANTs for who did the work, so no server sends invitations. Bound items get log_time(), time_log(), time_spent(), amend_time() and delete_time(); tasks get a timer (X-PYCAL-TIMER-START, removed when stopped); summarize() sums per budget line. The time-log capability is LOSSY where a tracker drops fields, which fake backends exercise until 2.5 brings real ones. On CalDAV it is FULL where caldav has hints for the server, UNKNOWN elsewhere, and unsupported in a calendar holding no events. Prompt: Deal with [roadmap item 1.6, the time-tracking model and API, postponed earlier; plan in an untracked document] Followup-Prompt: (asked which branch to build on) Stack on PR 24 Followup-Prompt: Do the needful to get PR 25 merged. [rebased onto main after PR 13 was merged] Prompts (comments made inline in the document while reviewing it): > (on plann's earlier design) The design notes in plann can be disregarded. > (on D3, suggestion to use ORGANIZER rather than ATTENDEE for who did the work) The attendee parameter `SCHEDULE-AGENT=CLIENT` or `SCHEDULE-AGENT=NONE` or 'Scheduling: none` or `Schedule-Reply: F` should probably work? though, it's needed to verify this somehow, and it may be difficult in the caldav-server-checker tool. Without METHOD, the server is also not supposed to send scheduling-invites - but I did once experince (sic) Zimbra spamming people with ten year old meeting invites when I tried restoring my calendar from a backup ... hm. (PARTICIPANT is of course the right solution, it was found in the next iteration) > (on D3) Multiple people can have attended an event, if using organizer then it's needed with one event per attendee - or can an event have multiple organizers? > (on D3) Journals is the thing meant for recording after-the-fact, can journals have attendees? Would they get scheduling emails sent? A journal entry can be liked (sic) to the time-tracking event. > (on D3) The tasks draft has put a lot of effort into assigning tasks, please consider if anything from there can be used - but that's probably only related to VTODO, and not a VEVENT? Time should be recorded also when participating in a VENVENT (sic), not only when working on a VTODO. > (on D4, X-PYCAL-PERCENT-COMPLETE) Do we need PERCENT COMPLETE in a time tracking event? It may sound useful, but it doesn't really belong in a VEVENT. One idea I had for plann (and which seems to work out to some extent) is to split a task into subtasks when I've partially completed a task. "clean the pantry" (completed) vs "clean the rest of the boat", and then use the estimated duration to indicate how many percent I believe I've done. But we could leave the PERCENT COMPLETE as a question to be resolved later. > (on D4, X-PYCAL-UNTIMED) I don't like introducing too many X-parameters. They should be listed and explained and justified for the rest of the team. Every X-parameter needs to be very carefully thought through. It's possible to have a rule that DTEND==DTSTAMP means the time is made up. (though, this does not work out very well with punch clock systems). We do have some X-parameters for source system, or the uid will indicate source system? So if the source system does not support anything else than "time spent", then it's safe to assume the DTSTART is made up. Do we need anything more advanced like that in the beginning? > (on D5, where entries go) Some CalDAV servers cannot be used for time tracking, period. The time tracking would eventually need to land in a separate calendar. I'm comfortable with that. > (on D6, scalar-only backends) Importing from the internal icalendar storage to the scalar-only backend works, but is lossy. Import the other way, and it's even more guesswork than with the `log(spent=4h)`. But even if it's just a scalar that is visibly stored, do some research on weather (sic) it's possible to get information on the transactions where the scalar is changed? > (on one PARTICIPANT per entry) If two persons in the same meeting logs different duration, then obviously it's needed with two entries, but it doesn't sound quite right to me to define that it always should be only one PARTICIPANT per event. > (on dropping percent-complete) Are there any systems that would have problems with round-triping if we drop the percent-complete on the time worked entry? > (on untimed entries) When starting to use timewarrior, it got a bit frustrating that I couldn't just log "I've spent 3 hours on this, 2 hours on that and 4 hours on something else after lunch". That's what I need to copy over to the accounting system. Excactly (sic) how many intervals for each customer and their exact start- and end-times is not important. Sometimes I will have spent the whole 9 hour window on multitasking between different tasks. In timew every task has to have a start time and an end time, and AFAIK they have to be given (ideally real-time in a punch clock manner). In the aw-watcher-afk-prompter I allow a time interval to be split into different tasks, and allowing a duration to be set on each of them. It's still recorded with a start time and an end time in the database, and I know it's not entirely correct, but at the end of the day it doesn't matter. > (on untimed entries, on the fact that it's impossible to rely on DTSTAMP==DTEND) There is also the timestamp CREATED that can be set, and it's optional. > (on untimed entries) What date one did the work on is usually of significance. An EVENT can take a date as DTSTART - but can it be combined with a DURATION given in hours without breaking the RFC? Would the servers accept it? > (on X-PYCAL-TIMER-START) The latter is to be a temporary attribute, to be removed after usage. > (on D1) Yes, we keep the marker > (on question 1, the marker) Keep marker > (on question 2, PARTICIPANT) Participant it is, but I think it's fair to allow more than one participant in an event. > (on question 3, the capability table) probably ok Assisted-By: Claude Opus 5.5 (1M context) Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
The suite stored ESTIMATED-DURATION as a bare timedelta, which icalendar writes as "2:00:00" for a property it does not type: invalid iCalendar that a backend could only pass by storing it untouched. The sample is now a vDuration, written "PT2H". Prompt: Deal with [roadmap item 1.6, the time-tracking model and API; found while summing estimates for it] Assisted-By: Claude Opus 5.5 (1M context) Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Disclaimer: Code and the text below the line are AI-generated, by Claude Opus 5.5, from the prompts:
Implements roadmap item 1.6, the time-tracking model and API, as designed in API_DESIGN §3.4 "Time tracking". Stacked on #24, which should be merged first.
VEVENTmarkedX-PYCAL-TIME-ENTRY, withRELATED-TOpointing at the task or event. Who did the work is an RFC 9073PARTICIPANT, never anATTENDEE, so no server sends invitations.log_time()(two of spent/start/end, or spent with a day),time_log(),time_spent(),amend_time()anddelete_time(), and collections gettime_entries(start, end). Tasks get a timer,start_timer()andstop_timer(), held inX-PYCAL-TIMER-STARTonly while it runs.calendaring.timetracking.summarize()groups entries into budget lines, keeping committed and spent time apart.time-logis FULL where entries round-trip. It is LOSSY withdetails["lost"]where a tracker keeps entries but drops fields, which the review research found is the common case (GitLab, RT, Kanboard, OpenProject, Gitea).total-onlycovers a backend that keeps only a sum. Two fake tracker backends in the tests run those branches until 2.5 brings real ones.ESTIMATED-DURATIONsample is now valid iCalendar.Left for later:
time-logdeclaration (2.1).