Re: Extending timeclock.el

[Eli Zaretskii]

> From: John Task <q01@disroot.org>
> Cc: emacs-devel@gnu.org
> Date: Sat, 06 May 2023 12:47:24 -0300
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > 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.
> 
> That works, too.  My thinking was that timeclock.el worked perfectly
> fine until now, and timeclock-modern.el would be a simple extension in
> order to support a different workflow.  However, it also makes room
> for improvement in other areas of the package, so I'll look into that.

The way we extend existing packages is by adding code to the existing
files, not by starting new FOO-x.el files.  This is a natural way of
extending them, even if the extension adds something that is only
loosely coupled with the previous functionalities.

> Yes, that's how I realized they exist.  But as I'm not well
> familiarized with the package, they are still pretty cryptic from my
> POV.  For instance:
> 
>   b  Set the current time balance, or "time debt".  Useful when
>      archiving old log data, when a debt must be carried forward.
>      The COMMENT here is the number of seconds of debt.
> 
> I understand every word here, and yet I don't really get what time
> balance is or when to use it.

I'm not sure this is being used.  Do you see any code that logs "b"
lines in the file?

> Also, old log data can be archived?

I'm guessing that this means you move the log file to some archive,
e.g., when a year ends or something.

> > 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?
> 
> OK, I think that's clearer now.  That kind of statistic was not
> possible at all in ETT, so I'll have to design it from scratch, but it
> sounds good.

You don't have to design and implement anything that didn't exist
unless you think it's a must-to-have feature.  We can always wait for
users to request such a feature in some distant future.  What I
described was just a rationale for having "O", and my point was that
allowing people to say the project is finished is useful even if for
now this is largely unused.

> I was thinking about something like that, too.  Basically,
> timeclock-modern, as it is designed right now, should ideally make
> three main additions to stock timeclock:
> 
> 1. A parser to retrieve information from the timelog file
> 2. Advanced statistic reports
> 3. A new optional workflow where it is able to track everything

Yes.

> Point 1 must explicitly support the current state of things, as it
> would be useless otherwise.  Point 2 also should support the default
> behaviour of timeclock, so all users can benefit from it; however,
> some things such as tags are not supported out-of-the-box as of now,
> while other things such as the 'b' or 'h' keywords don't make much
> sense for the new behaviour.  So, statistic reports will depend on
> what workflow the user chooses.

Right.

> As for point 3, it is the most complex one because I haven't come to a
> clear solution of how to implement it properly yet.  For now, I think
> a user option which redefines the behaviour of some commands such as
> timeclock-in and timeclock-out is the best path to follow.

If that works, I agree it's the best.

> And the thing is, the new workflow will probably slightly modify the
> timelog format.  Currently, my custom tm-clock-in (which would be
> the new 'timeclock-in' once the user opts-in into the new worflow)
> gets rid of the letter code altogether, somehow breaking backward
> compatibility.  Maybe that's not a bad thing though, because if the
> user opted into the new workflow, they probably don't care about
> that.

As I said, the timelog file could announce what kind it is of.

> > 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.
> 
> Yes, I have tested that kind of timelogs and everything has gone well.
> I was thinking on sligthly more complex files, maybe with 'O', 'h' and
> 'b' here or there.  Maybe I'm exaggerating a little, but it feels
> wrong to not test it with real timelogs :)

You can build tests using the ert package.  We use it in our test
suite (under the test/ subdirectory of the Emacs source tree).

> > 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.
> 
> Now that I think about it, maybe modifying timeclock-in in order to
> support that workflow based on user options is a good idea.  That way
> I don't have to support a separate tm-clock-in.  That's also another
> argument in favour of forking timeclock instead of developing a
> separate file.  I'll look into that.

Thanks.