Introduce some kind of declaration file for links across commit messages and docs.
Problem to solve
Provide the ability to define where links to issues, labels, milestones etc. go by declaring their targets in a file.
Further details
Imagine a repository that is being mirrored from one Git platform to another one, e.g. from GitHub to a GitLab instance / GitLab.com.
You might see commits in the commit history like this one:
fixes #47716 where email confirmation fails after adding additional emails
What's the problem?
In this example the commit mentions an issue on another Git platform. The commit on GitHub refers to an issue (#47716 (closed)) that exists in the origin repository on GitLab, so it doesn't point to the correct location but instead leads you to the issue on the platform you're reading the commit message at (if it happens to exist).
If the developers of said team mirror their code to various platforms, move their main repository a lot or use ticket systems on various Git platforms (which sounds like bad practice to me and would render this solution useless anyways), references to the respective issues get lost and someone who'd like to read up what was going on there wouldn't find the actual issue they were looking for.
Proposal
Declare a path for a file (like for example /.linkrefs
) in the repository (root), that contains information to where which kind of link (issue, label, milestone) points to.
This most current state relative to the point in history of the commit viewed will be read and processed when the commit message is being rendered. This results in links that always point to the correct location across the repository's history.
The file The file could be similar to those Linguist files GitHub has, or possibly be something like a JSON file that could look like this:
{
"targets": {
"issue": "https://gitlab.com/gitlab-org/gitlab-ce/issues/%s",
"tag": "..."
}
}
In this example, a reference to #123456789
would then point to https://gitlab.com/gitlab-org/gitlab-ce/issues/123456789
.
What does success look like, and how can we measure that?
If a user views an old commit message or document before a point in time where e.g. that project moved from GitHub to GitLab and that text includes a link to an issue (or similar), GitLab will render links according to the state of the .linkrefs
file back in that point in history. Everyone can find the correct target for the link they click at.
If properly implemented, it could also become a feature other Git repository platforms would like to implement and even become some kind of standard(?), which I think would be nice for GitLab too.
That would probably encourage developers to share their code across more platforms (at least as mirrors) and make research for issues and such easier.
Links / references
I found this issue after writing this proposal, but it seems to be related at least a little bit, even if it's not the same idea:
https://gitlab.com/gitlab-org/gitlab-ce/issues/30204
I also read a feature proposal somewhere a few months ago (I think it was for someone's Markdown flavour) which suggested some kind of configuration for @mentions to decide where it points to (e.g. Twitter), but I can't find that right now.
Thanks for reading my proposal!