mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
96 lines
2.8 KiB
Text
96 lines
2.8 KiB
Text
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.
|
|
|