GothenburgBitFactory/timewarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/timewarrior.git synced 2025-07-07 20:06:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Docs: Added API specification, eliminated reports.txt

Browse source
This commit is contained in:
Paul Beckingham 2016-04-10 12:33:45 -04:00
parent 1cd019167d
commit c65833b706
3 changed files with 132 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

103
doc/api.txt Normal file
View file

@ -0,0 +1,103 @@
Extension API
=============
Timewarrior reports are written as extensions, which uses an API to provide
filtered data and configuration to the external command. This is a one-way
process, and the extension has no way to communicate back to Timewarrior.
However, future rules features will allow this.
Integration
-----------
Simply placing an executable script/program in the ~/.timewarrior/ext directory
is sufficient to configure nad enable the extension. The name of the program is
leftmost matched, so that this extension:
~/.timewarrior/ext/my_report.py
Can be run using all of the following commands, depending on the uniqueness of
the name:
$ timew report my_report.py
$ timew report my_report
$ timew report my_r
$ timew my_report.py
$ timew my_report
$ timew my_r
APІ Mechanism
-------------
Timewarrior will provide all configuration and filtered data in JSON format to
the standard input of the extension program. There are no command line arguments
used, and no environment changes. The extension must be a standalone executable
entiry, as Timewarrior will fork/exec and not invoke a shell.
All standard output generated by the extension is captured and presented
verbatim by Timewarrior. There may be additional text prepended or appended to
this.
Input Format
------------
The input format looks like this:
name1: value1
name2: value2
version: 0.1.0
...
[
{ ... },
{ ... },
...
]
Specifically, there is an initial block of name/value pairs, which is a copy of
the complete current configuration data. It has the form:
<name>: <value>
This configuration block includes the Timewarrior version, so that multiple
releases maybe supported by the extension. Additionally, other data is included
with the 'temp.' prefix, indicating that it is not part of the configuration
data, but may be of use to the extension. For example:
temp.db: /home/user/.timewarrior
temp.report.end: 20160401T000000Z
temp.report.start: 20160430T235959Z
temp.report.tags: "This is a multi-word tag",ProjectA,tag123
After the configuration block, there is a single blank line to separate it from
the JSON data.
The JSON data is a single JSON array, containing zero or more Interval objects
that look like this (line breaks for clarity):
{"start":"20160405T162205Z",\
"end":"20160405T162211Z",\
"tags":["This is a multi-word tag","ProjectA","tag123"]},
Here the presence of the "end" data means this interval is closed, i.e. not
actively being tracked. There is one JSON object per line. The timestamps are
ISO format UTC.
Guidelines
----------
A well-behaved extension is one that follows these guidelines, and conforms to
the general pattern of behavior exhibited by Timewarrior. The guidelines are:
- Obey the 'verbose' setting, and if the value is neither on/1/yes/y/true, then
consider it 'off', and generate minimal output, which may be no output at all.
- Obey the 'debug' setting, and if the value is either one/1/yes/y/true, then
emit helpful feedback, but only that which can be useful for debugging a
problem, which may be no output at all.
- Obey the 'confirmation' setting, and if the value is either one/1/yes/y/true,
then obtain user permission interactively before proceeding with any data
modification. Do not rely on, or implement a 'force'-like feature.
--- Raw Notes ---

29
doc/project.txt
View file

@ -40,6 +40,24 @@ Non-Goals
- No features without a compelling use case.
Reports
-------
Anticipating all reporting needs is impossible, therefore custom reports are
required. Rather than copy the Taskwarrior design where flexibility is provided
via configurable options for fixed-format reports, Timewarrior will use a more
flexible approach of providing configuration and data via an extension API.
This will not limit the kind of reports or supported formats that can be added.
Timewarrior will ship with several reports, which serve as example extensions
for users to modify and improve, perhaps contribute back to the project.
Purely as an example of what might be implemented, here are some report mockups:
./report.week.txt
./report.day.1.txt
./report.exc.week.txt
Tags
----
Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
@ -130,3 +148,14 @@ data.
command, instead of "stop" use "forgot" or directly "edit". Then I would
like to express either "stopped 30min ago" or "it lasted only 1hour”.
- Need a JSON --> CSV converter, for spreadsheet folks. Therefore csv.py could
be an extension that converts the format.
- Use display granularity/resolution to see more or less details. This would
combine nicely with a tag hierarchy. (Tomas Babej)
- Need reports to help users doing fixed-rate work - finding the longest task
for example.
- If an interval has more than one tag with a defined color, and is being
rendered, then use the first tag color. It doesn't really matter which.

96
doc/reports.txt
View file

@ -1,96 +0,0 @@
Reporting
=========
Anticipating all reporting needs is impossible, therefore custom reports are
required. Rather than copy the Taskwarrior design where flexibility is provided
via configurable options for fixed-format reports, Timewarrior will use a more
flexible approach of providing configuration and data via an API. This will not
limit the kind of reports or supported formats that can be added.
Requirements
------------
Timewarrior will ship with several reports, which serve as example extensions
for users to modify and improve.
Timewarrior will handle the command line options for reports, then pass off a
standardized set of parameters to the report extension. These parameters will
include:
- Date range. Although Timewarrior might support "last month" as a reporting
range, the extensions themselves would be passed precise values, therefore
reducing the complexity of the extensions.
- Data will be filtered by Timewarrior, so that extensions will not need to
reimplement this.
- Reports will be sized according to need, not according to available terminal
width. If a report does not fit in a window, it is not an error.
There will be a default report, which is configurable so that one of the reports
or commands can be the default.
Report Mockups
--------------
Purely as an example of what might be implemented, here are some report mockups:
./report.week.txt
./report.day.1.txt
./report.exc.week.txt
TBD (calendar like "task calendar" with table below)
TBD (timeline, l-r)
TBD (table with subtotals)
Example Commands
----------------
Here are some provisional examples of report commands:
$ timew report day [monday] [±<tag> ...]
$ timew report week [±<tag> ...]
$ timew report month|quarter|year
Report API
----------
The report API is simple - it invokes a program and feeds it input. All output
is generated by the program. When running this command:
$ timew report x ...
Timewarrior then runs this:
$ ~/.timewarrior/extensions/x.*
With standard input consisting of:
filter: ...
name1: value1
[
{ ... },
{ ... },
...
]
That is, the input is line-oriented, with first a header block of name/value
pairs, then a blank line, then the JSON filtered data. The header block has all
configuration names flattened, i.e. no hierarchy.
--- Raw Notes ---
- Need a JSON --> CSV converter, for spreadsheet folks.
- Use display granularity/resolution to see more or less details. This would
combine nicely with a tag hierarchy. (Tomas Babej)
- Need reports to help users doing fixed-rate work - finding the longest task
for example.
- If an interval has more than one tag with a defined color, and is being
rendered, then use the first tag color. It doesn't really matter which.
- Need a formal API description, for extension authors.