Consistent handling of "Needs maintenance" and "OC Team entry" log properties

[following5]

This issue builds on #373. It presumes that the new log entry field needs_maintenance - as proposed in #373 - is implemented.

Currently there is an inconsistency in the OKAPI regarding the handling of "needs maintenance" logs. When submitting logs, the NM information is provided as flag needs_maintenance=true. When retrieving logs, it is returned as type=Needs maintenance (for OCPL sites). To get this straight, I propose to discard the log type "Needs maintenance" and return "Comment" instead, while the NM information is returned as needs_maintenance=true. This needs a new type2 field while deprecating type, so that existing applications are not broken.

OKAPI also documents a log type "Maintenance performed" (internal ID 6). I do not see this anywhere in the current OCPL code; neither does OCDE implement it. Anyway, for consistency I suggest to deal with it in the same way as described above for "Needs maintenance": Return it as "Comment", with needs_maintenance set to clear.

The "OC team entry" log property is a similar case. OKAPI currently does not allow to submit it, but it would be straightforward to handle it the same way as "Needs maintenance". So the "OC team entry" log type should be discarded, too (returned as type "Comment"). The team-entry flag is already returned as oc_team_entry=true.

I implement this proposal in a separate branch, which is based on #373. It may be discussed later; I already open it now becaus it shares the new needs_maintenance log entry field with #373. For transparency, it should be mentioned that this change would move the OKAPI log entry type logic from rather resembling OCPL to rather OCDE. However, OCDE just implements the OKAPI logtype-sumbitting logic, and rationale for this issue is to remove an inconsistency in OKAPI (between submitting and retrieving logs).

[following5]

The sample implementation is here. It has much less lines of code than the explanations above. :-)

[following5]

I have rebased the sample implementation on the current master and removed the "performed maintenance" thing. The "performed maintenance" logic of OCPL and OCDE is so fundamentally different, that I do no longer see a chance to unify it this way.

To sum it up: I propose to deprecate the type log entry field and introduce a new type2 field, which differs from type only by dropping the log types "Needs maintenance" and "OC team comment" - they are returned as "Comment" instead. This would

• remove inconsistencies between submitting and retrieving logs, and
• remove redundancy within the log entry fields.

[wrygiel]

Somehow, I didn't stumble on this thread previously, sorry about that. Had a glance on the implementation now, and it seems ok!

[wrygiel]

I guess some OCPL developers may find it a little strange (because they're used to seeing these as separate log types), but your change is logically valid.

[following5]

Yes, they may find it as strange as submitting 'needs maintenance' through OKAPI. :)

[wrygiel]

Huh, I just liked your comment, GitHub is becoming facebookish. ;)