Re: Extending timeclock.el

[Eli Zaretskii]

> From: John Task <q01@disroot.org>
> Date: Fri, 05 May 2023 16:15:02 -0300
> 
> Hello.  A little context, first; some days ago, I submitted a request
> for including a package in the NonGNU ELPA repository.  The package in
> question was a time tracker named ETT.  However, Eli pointed out that
> instead of creating a new package I could, for instance, extend the
> built-in timeclock.el instead.  To be honest, I didn't like the idea
> at first, but looking at the code I quickly realized it wouldn't be
> that hard.  At least, not as dramatically hard as I thought.
> 
> So I started this: https://gitlab.com/q01_code/timeclock-modern

Thank you very much for working on extending timeclock.

> [This wasn't my first name choice, but turns out timeclock-x is
> already taken]

Why not simply add the code to timeclock.el itself?  You can for now
fork it and develop it separately; later, we will merge the changes.

> So far, I managed to write a series of parsers for the timelog format,
> as well as a basic API for retrieving information from it.  This
> should allow me to port all the relevant code from ETT without issues.
> However, I'm not really familiarized with timeclock, so I can't assert
> my design choices so far have been ideal.

By "timelog format" do you mean the format of the log file
read/written by timeclock.el, or do you mean some other format, which
Emacs currently doesn't use?

> + The letter code at the start of every line was the most difficult
> part.  ETT (and a lot of modern time trackers as well) don't
> understand what clock-out means, as the idea is to clock everything;
> the user just clocks-in different activities.  So, I dropped 'i' and
> 'o' for my custom tm-clock-in altogether.  As for the parser, it
> understands 'o' as the start of a so-named 'Untracked' item/project.
> That way it can read existent timelogs just fine.  This is hard
> enough, but turns out there are also other codes ('h', 'b' and '0').
> I interpret '0' as an 'o' and ignore the other ones, but I'm not sure
> if this is correct.

The codes are documented in the doc string of timeclock-log-data
(assuming it is up-to-date ;-).  There's no "0" there that I could
see, but there is "O" (upper-case letter O).

As for the "clock-out" issue: like I said, time trackers used for
tracking work activities do have both 'o' and 'O'.  The former means
"end of workday", the latter means "this activity will never again
appear, because its project is 'finished'".  The former can indeed be
represented as the start of "untracked" activity, but the latter must
be also explicitly supported, because a reasonably useful report or
statistics could deal with projects which were already completed.  For
instance: how many projects were completed the last year?  Or: what is
the average amount of time spent per project until it's completed?

If you find actions that are difficult to represent in the usage
pattern you envisioned for ETT, we can have two separate workflows
supported by timeclock: one workflow for which timeclock was
originally designed, where it tracks "work hours"; the other where it
tracks everything.  We could have the type of the workflow described
in the COMMENT of the 'i' entry.  Or we could ask the user up front to
specify which workflow is intended, and have that encoded in the
header line of the timelog file (if we think these two workflows are
mutually exclusive).

> + As I make a lot of decisions such as the last one from ignorance,
> I'm clueless about how well the parser (and the API) works for real
> timelog files.  If anybody wants to test that, it would be
> appreciated.

I have only ever used timeclock in a very simple workflow, with a
single "project" into which I was clocking in and then clocking out
every day.  So my timelog file is a series of 'i's and 'o's, something
that you can easily generate yourself.  If specific issues are of
interest, please ask more specific questions.

> + As the original timeclock-in doesn't support inputting tags (as well
> as other features I need), I wrote a custom tm-clock-in.  But I'm not
> sure if this is the right approach.  And redefining timeclock-in would
> be even worse, for sure.

Why "worse"?  Can't we do this in a backward-compatible manner, like
based on user options?  And if worse comes to worst, we can add a
whole new set of commands to support the "track everything" workflow
you had in mind for ETT.

> I'll eventually contact the original author as well, but I wanted to
> know of any other opinions here first.

John Wiegley, the original author is somewhat busy these days, but we
can add him to this discussion right away.  Here, done.