Unify all Diff File responses from merge request APIs
As the groupcode review frontend team moves to more and more complex code that joins Diffs with other pieces of data like discussion notes, it's more important than ever that what's returned as a Diff File matches the response of other endpoints that also contain Diff Files.
The most pressing reason for this is the ability to match two files together with no ambiguity.
Here are the three most common Diff Files are returned by three different API endpoints:
-
[u]
= user or group -
[p]
= project
/[u]/[p]/-/merge_requests/1/diffs_metadata.json |
/[u]/[p]/-/merge_requests/1/diffs_batch.json |
/[u]/[p]/-/merge_requests/1/discussions.json |
---|---|---|
|
|
|
Problem
As you can see, there are noticeable variations between the files.
In the case of the metadata, this is intentional. However, there isn't enough contextual information shared across all of the file representations to unambiguously match them.
Matching Scenarios
To disambiguate and match files across projects, merge requests, and merge request versions while accounting for changes (or lack thereof) across MR versions, the FE needs:
- the group or username
- the project
- the merge request ID
- the git blob ID
- the file path
- the file's mode
- the diff action (added/deleted/modified)
Missing data
The three variations of the Diff File are missing:
/[u]/[p]/-/merge_requests/1/diffs_metadata.json |
/[u]/[p]/-/merge_requests/1/diffs_batch.json |
/[u]/[p]/-/merge_requests/1/discussions.json |
---|---|---|
|
|
|
Solution
I propose a standard base shared among all representations of a Diff File:
- the group or username
- the project
- the merge request ID
- the git blob ID
- the file path
- the file's mode
- the diff action (added/deleted/modified)
Other useful data
Sometimes, it's helpful to know the last MR version in which this file was changed.
We can infer this from the git blob ID which shouldn't change if the file hasn't been modified, but it would be convenient to have a definitive source of this information.
We could include:
- the MR version in which this file last changed
Existing Shortcuts
file_identifier_hash
includes the file path and the diff action, which could be re-used in a pinch, but having the values available as individual properties would be preferable.
Example base Diff File shared among all representations
{
"userOrGroup": "gitlab-org",
"project": "gitlab",
"mergeRequest": 123456,
"lastChangedInMergeRequestVersion": 5,
"gitId": "abcdef1234567890",
"path": "/the/full/file/path.file",
"mode": "0755" // OR "u=rwx,g=rw,o=rw"
"action": "modified"
}
Tasks
-
Add userOrGroup
todiffs_metadata.json
Diff Files -
Add userOrGroup
todiffs_batch.json
Diff Files -
Add userOrGroup
todiscussion.json
Diff Files -
Add project
todiffs_metadata.json
Diff Files -
Add project
todiffs_batch.json
Diff Files -
Add project
todiscussion.json
Diff Files -
Add mergeRequest
todiffs_metadata.json
Diff Files -
Add mergeRequest
todiffs_batch.json
Diff Files -
Add mergeRequest
todiscussion.json
Diff Files -
Add action
todiffs_metadata.json
Diff Files -
Add action
todiffs_batch.json
Diff Files -
Add action
todiscussion.json
Diff Files -
Add gitId
todiffs_metadata.json
Diff Files -
Add path
todiffs_metadata.json
Diff Files -
Add mode
todiffs_metadata.json
Diff Files
Optional Tasks
-
Add lastChangedInMergeRequestVersion
todiffs_metadata.json
Diff Files -
Add lastChangedInMergeRequestVersion
todiffs_batch.json
Diff Files -
Add lastChangedInMergeRequestVersion
todiscussion.json
Diff Files