Making the time tracking information in the note API machine readable
Description
This feature proposal is extracted from this bigger ticket: #33211 (closed). You may also want to check this original ticket if some context is lacking.
We are in the process of migrating our Trac setup to GitLab EES. We are heavily using time tracking internally, and thus we need some robust and easy way to access time tracking information of notes.
Right now, when accessing the note API we get the following types of data:
{
"id":1214,
"body":"added 1d of time spent",
"attachment":null,
"author":{...}
...
}
The problem here is that:
- There is no way to discover time tracking information but by parsing all the
body
of all the notes - This assumes the body text will never change
The use case for having access to this kind of information at the note API level is mostly report generation, and report validation.
Examples with our workflow: for ease of calculation of time spent and reports, we are using webhook received from Trac with the time information in there. On a regular basis, we regenerate various reports and various aggregates only using the Trac time value to compare them and ensure no webhooks were lost because of a failure.
With the current note API of GitLab this kind of task will be harder, and not as robust since it will involve parsing natural language.
Proposal
Our proposal would be to add more machine readable informations about what the note is or changed to the state of the ticket. For the case that most interests us (the time tracking data), it could look like this:
{
"id":1214,
"body":"added 1d of time spent",
"machine_time_change": 86400,
"attachment":null,
"author":{...}
...
}
A more generic way of doing that could include the actual slash command, and a generic machine version of the argument of the command:
{
"id":1214,
"body":"added 1d of time spent",
"change_command": "/spend",
"machine_body": 86400,
"attachment":null,
"author":{...}
...
}
This last version could help support other slash command and make those easily parsable for the consumer of the API (but out-of-scope for this proposal)
The advantage of having this kind of machine readable are mostly about the easiness of creating consumer of the API, and robustness since there is no parsing required.