Add categories WebAPI

[Piccirello]

Closes #5330.

[glassez]

Thank you!

[Piccirello]

How should we track the API change resulting from this PR? Before release 4.1.4 is cut, the web API version will need to be bumped and the wiki updated. I know we discussed the idea previously.

[glassez]

web API version will need to be bumped

@sledgehammer999 do it before release.
We can help it by maintaining corresponding comment near API version definition and update it with each affected PR.

and the wiki updated.

I think the current approach (we just change wiki without any versioning) is incorrect. Users can use on different application versions providing different API versions.

[Piccirello]

Maybe we can track the WebAPI changes in an issue while we’re between versions. I like that more than using the source code as a temporary log.

I think the current approach (we just change wiki without any versioning) is incorrect.

I’ve tried to partially address this by explicitly listing changes between API minor version in the Changes section.

[glassez]

Maybe we can track the WebAPI changes in an issue while we’re between versions.

I have no general objections.
What exactly should be in this Issue?

I’ve tried to partially address this by explicitly listing changes between API minor version in the Changes section.

It seems iineffective to me.
If user has no latest app version it still can't see appropriate api documentation. It just sees that something has changed since its version.

[glassez]

@Piccirello, shouldn't we change API version in first affecting PR? Currently we may have outdated version between releases. (We still can track it in corresponding Issue)

[Piccirello]

What exactly should be in this Issue?

Probably a list of PRs with webapi changes, as well as wiki text describing the changes.

It seems iineffective to me.

I agree, but I think it’s better than what we had before. There’s still room for improvement.

shouldn't we change API version in first affecting PR? Currently we may have outdated version between releases.

I think we should actually. One issue I can think of is where I have multiple concurrent PRs open: which should include the version bump? I guess if both PRs have it then git will handle it in the merge.

[glassez]

I think it’s better than what we had before.

I'm not suggesting you take a step back. On the contrary, we can (and should) do it even better. Add new things marked as "since v2.x.y" and don't remove the old ones but just mark it as "until v2.x.y". If we change format of some thing (like you done with "categories" value in "sync/maindata) we just have to mark old as "until..." and add new marked as "since..." (like on "cppreference.com").

[glassez]

One issue I can think of is where I have multiple concurrent PRs open: which should include the version bump? I guess if both PRs have it then git will handle it in the merge.

Each PR should be considered separately since you don't know what exactly will be merged first. Then you just rebase remaining PRs to resolve conflicts (as we do in case of any other conflicting PRs).