Documentation clarification of "project" and "worker" concepts

[gsvarovsky]

In the docs, a worker and project are added in distinct array positions:

POST https://time.pondersource.com/v1/worked-hours
Authorization: Basic timeld ***
/* timestamp, worker, project (plus amount and description, not in docs) */
["2022-08-15T10:36:26.127Z","worker","test/ts1",0,"testing"]

In the response, the 'worker' is assigned to the API account holder, and the project concatenates the given worker and project:

[
{
"worker": "timeld",
"project": "worker:test\/ts1",
"timestamp_": "2022-08-15 10:36:26",
"amount": "0",
"description": "testing"
}
]

In the update-entry command, the 'project' assumes this concatenation, so a no-op update for the above data looks like this:

POST https://time.pondersource.com/v1/update-entry
Authorization: Basic timeld ***
/* timestamp, project, amount, description, id (currently not knowable :) */
["2022-08-15T10:36:26.127Z","worker:test\/ts1",0,"testing",123]

Please can you confirm this is correct?

[ishifoev]

@gsvarovsky Yes I will update this information, send you again and check it

[michielbdejong]

Ah, those docs are wrong then! This is how you use the worked-hours command:

0. "worked-hours"
1. date, e.g. "20 September 2021"
2. client, e.g. "stichting" or "nlnet-timesh"
3. project within client, e.g. "Peppol for the Masses" or "Federated Timesheets"
4. number of hours worked on that date, e.g. 4
5. (optional) description of work performed during those hours

@ishifoev can you find the misleading docs and fix them?

[michielbdejong]

The reason to have client and project separately is that PreJournal needs to determine the value flows based on that. It creates a movement of type "worked" from the worker to the project account within the client. The "account:subaccount" syntax is taken from Plain Text Accounting, see e.g. https://hledger.org/1.26/hledger.html#basic

[michielbdejong]

@gsvarovsky apart from the misleading docs we unfortunately gave you, thanks for flagging this as something confusing, it indeed is, even when using the correct docs!
The worked-hours command has client and project separately and the update-entry command (and I think the print-timesheet-* commands too) have "client:project" as one of the required parameters, and then also call that "project".

So we should have three names:

• one for strings like "stichting" ("client"?)
• one for strings like "Peppol for the Masses" ("project"?)
• one for strings like "stichting:Peppol for the Masses" (also "project"?)