I'm having some trouble making sense of the list diff API endpoint. It was acting weird before T299144 Change GET /api/lists/{list_pk}/revisions/{id}/ to emit full info on tools contained in the list, but now the "operations" (add, remove, replace...) that happen between two diffs when removing tools from a list seem even more chaotic.

List of steps to reproduce

1. Create a new list, containing only one tool (toolforge-pywikibot)
2. Save the list
3. Edit the list, adding a second tool to it (toolforge-spacemedia)
4. Save

So far, so good. The expected "add" op is there if you inspect /api/lists/{list_pk}/revisions/{id}/diff/{other_id}/.

1. Now, edit the list again, removing the first tool from it (toolforge-pywikibot)
2. Inspect the diff api endpoint again

What I thought was expected behavior:

1. The tool at index 0 was removed, which should give rise to a "remove" op
2. As a result, the second tool, previously at index 1, moved to index 0, so a "move" op?

What is actually happening:

{
  "original": {
    "id": 972,
    "timestamp": "2022-01-25T12:48:58.182361Z",
    "user": {
      "id": 2,
      "username": "SStefanova (WMF)"
    },
    "comment": "added spacemedia tool after pywikibot",
    "suppressed": false,
    "patrolled": false
  },
  "operations": [
    {
      "op": "replace",
      "path": "/tools/0/keywords/0",
      "value": "commons"
    },
    {
      "op": "add",
      "path": "/tools/0/keywords/1",
      "value": "wikimedia commons"
    },
    {
      "op": "replace",
      "path": "/tools/0/name",
      "value": "toolforge-spacemedia"
    },
    {
      "op": "replace",
      "path": "/tools/0/title",
      "value": "Find free media released by space agencies missing in Wikimedia Commons"
    },
    {
      "op": "replace",
      "path": "/tools/0/description",
      "value": "Explores NASA, ESA and other space agencies media libraries to find free images (PD / CC-BY-SA 3.0 IGO) not yet imported to Wikimedia Commons, based on the image SHA-1."
    },
    {
      "op": "replace",
      "path": "/tools/0/url",
      "value": "https://spacemedia.toolforge.org/"
    },
    {
      "op": "replace",
      "path": "/tools/0/author",
      "value": "Don-vip"
    },
    {
      "op": "remove",
      "path": "/tools/1"
    }
  ],
  "result": {
    "id": 973,
    "timestamp": "2022-01-25T12:50:55.785137Z",
    "user": {
      "id": 2,
      "username": "SStefanova (WMF)"
    },
    "comment": "removed pywikibot. spacemedia is left",
    "suppressed": false,
    "patrolled": false
  }
}

So... is this expected behavior, and I just have to beat the output into an appropriate form for diff-viewing, or is it punishment for having wanted the list revisions API changed? xD

In T298698#7648812, @Slst2020 wrote:

So... is this expected behavior, and I just have to beat the output into an appropriate form for diff-viewing, or is it punishment for having wanted the list revisions API changed? xD

This sounds very much like unintended changes to what is being diffed. Specifically this looks to me like the full tool records being diffed rather than just their names. I did not check for that when reviewing @Raymond_Ndibe's patch for T299144: Change GET /api/lists/{list_pk}/revisions/{id}/ to emit full info on tools contained in the list, but in retrospect I should have.

The content for the diff is prepared in the toolhub.apps.lists.views.ToolListRevisionViewSet._get_patch method. In that method we are using the ToolListHistoricVersionSerializer class to prepare the JSON output for each revision to feed into the diff generation. That is the serializer that was changed in T299144 to output each tool in the list using a SummaryToolSerializer. This would lead to the diff output you are now seeing. We do want this new ToolListHistoricVersionSerializer behavior for viewing historic revisions, but we want the older behavior for generating diffs.

The most likely fix would be to introduce a new serializer which works like ToolListHistoricVersionSerializer did before rWTHU355e78c4dce7: lists: emit full info on tools contained in a historic revision specifically for use inside of toolhub.apps.lists.views.ToolListRevisionViewSet._get_patch. This would return the diff generation to only comparing the contents and order of the list of toolinfo record names rather than the summary details of each of those toolinfo records.