Merge Trains API docs are lacking in explanations and examples

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

Problem to solve

• What product or feature(s) affected?
  • Gitlab Merge Trains API
• What docs or doc section affected? Include links or paths.
  • https://docs.gitlab.com/ee/api/merge_trains.html
• Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs?
  • Merge trains API overall; all sections

Further details

A few observations about this doc page (and the API itself) that make the API hard to understand/use:

• The docs say that the endpoints return "Merge Trains" but it's not really well-defined what a "Merge Train" API object represents. Specifically:
  • Merge trains can have multiple merge requests, but in the /projects/:id/merge_trains endpoint response, there is a single merge_request field, and it's not clear which MR this will be, or if there will be multiple entries in the response for each merge request in any merge train
  • The same is true for pipelines in a merge train, since each MR in a train can have an active (or complete) pipeline
  • If my guess is correct and there will be an entry in this response for each MR in any merge train, this is confusing in a different way; the length of the response could be longer than the number of active merge trains
• The /projects/:id/merge_trains/:target_branch is described as "List merge requests in a merge train", but the response format is the same as the "List Merge Trains for a project" endpoint, despite being described as returning different resources ("merge request" vs "merge train")
• The sorting is described as "Return Merge Trains sorted in asc or desc order. Default is desc." It is not mentioned what attribute of a "merge train" object is being used for sorting. Ostensibly, it could be the order in the train, but...
• The order in the merge train is not returned. The user is left to assume that the response is ordered by position in the merge train, but nowhere is this made explicit.

Proposal

Doc updates:

1. Clarify what a "merge train" API object represents
2. Clarify what is returned in the /projects/:id/merge_requests response when there are multiple merge trains each with multiple MRs
3. Make the sort order semantics explicit
4. Add example merge train scenarios (with diagrams representing the train status for multiple projects) and the resulting API responses

API additions:

1. Provide a way to identify which MRs belong to the same train, particularly when filtering scope=complete
2. Include the train order in the API response
3. Perhaps: add a merge_requests field that includes all MRs in a train
   • This is conditional on the resolution of the doc update (2), as I'm not clear on what the current semantics are, and this could be a breaking change
   • I could see this being better handled in a separate issue, but I wanted to mention it in this context first.

Who can address the issue

Other links/references