Allow additional kinds of entity comparison using compare page links/repository API
Problem to Solve
There are different kinds of entities in GitLab that are really just SHAs in the repo (environments, branches, tags). We have a compare method in our API, but at the moment it assumes you're passing a commit SHA or branch name. If we add a type selector to the API call, we can support more kinds of things, in particular environments as entities is an interesting one, but in the future this can be expanded to support many kinds of comparison of entities that have a state that corresponds with a git SHA.
This can also be delivered in a nicely backwards-compatible way by retaining the existing behavior as the default when a type is not specified, ensuring we don't create a new problem by solving this one.
Description
Compare page uses reference names in two place. First one is new compare form, that is using link like
https://gitlab.com/gitlab-org/gitlab-ce/compare?to=v11.0.0&from=master
then it redirects to the actual compare page, that shows comparison with like like
https://gitlab.com/gitlab-org/gitlab-ce/compare/v11.0.0...master
Since Git allows to have a tag and a branch with a same name, pointing to different SHA, we can have master
branch and a master
tag and this makes links / comparison page ambiguous.
We are now going to add support to compare environments with branches / tags, which will make things even more ambiguous. Imagine having production
environment, having production
branch, and perhaps production
tag as well. All this is possible.
Proposal
We talked about proposal in https://gitlab.com/gitlab-org/gitlab-ce/issues/47882#note_82047960
We agreed with @winh and @bikebilly that we can support links like
https://gitlab.com/gitlab-org/gitlab-ce/compare?to=tag:v11.0.0&from=branch:master
and
https://gitlab.com/gitlab-org/gitlab-ce/compare/tag:v11.0.0...branch:master
and still support the old path for a backwards compatibility.
Documentation Notes
The compare API documentation will need to be updated with the additional options.