Feature highlight: Move issues between projects

In 8.6 we added a feature allowing you to move issues between projects.

If you work on multiple projects, it's possible to accidentally create an issue in the wrong issue tracker. It's a seemingly simple mistake that is easy to miss. Let's say you don't catch it right away and you do a decent amount of work on the wrong project. Now, your "seemingly simple" mistake just became a bigger one. We've all been in this position before. With our 8.6 release, we want to avoid the panic that can come from creating an issue in the wrong project. Now, if you create an issue in the wrong project, you can easily move it to the right one.

When you move the issue, the original issue will be copied, closed, and then referenced. This process makes sure nothing is lost in the move.

Additionally, anyone who is subscribed to the issue will get a notification that the issue was moved, with a link to the new location. This will, of course, depend on your notification settings.

It's a relatively simple feature, but it was tricky to implement.

Behind the scenes: Moving issues between projects

At first, moving issue between projects seemed like an easy task. However, we encountered a tricky problem with references in the issue description or comments.

Suppose we have a project called Alice, and we created an issue inside it:

Hey, this issue is related to #123 and the solution is implemented in !456.

Now let's suppose we want to move this issue to Bob. The reference #123 points to an issue in Alice. Similarly, !456 points to a merge request in Alice as well. If a user moves an issue to Bob, these references need to be updated so that they continue pointing to Alice, not Bob. Otherwise, the resulting references would link to the wrong project. The same goes for snippets, labels, commits, etc.

We knew that we needed to fix these references by using GitLab's Markdown cross-project reference notation. However, at the time, not everything in GitLab supported this notation. For example, labels (e.g. ~"My Label") could not be shared across projects. We had to fix that, so we did via Merge request !2996.

Another step was simply substituting #123 with gitlab-org/gitlab-ce#123. But it is possible you could have text like this:

Hi, this is a duplicate of http://gitlab.com/gitlab-org/gitlab-ce/issues/123.
Also see documentation docs.gitlab.com/ee/some-page#123. Also take a look at this code:

    puts 'some code' #123 is a comment

So we know that this description holds a reference to issue 123 but we do not know where it is, or how to substitute it in the right place. We needed to modify the source text. However, changing the source text would interfere with Markdown. To solve this, I tried some prototypes but couldn't find a better solution than writing yet another parser for Markdown that would support the full Abstract Syntax Tree of Markdown. This would add support for mutable nodes in a tree, allowing us to modify text where needed.

However, once I started this work, I felt that this was a complicated solution so I decided to look for a boring solution. I reached out to my fellow developers on the team to find a better boring solution. After sometime, Kamil helped me and we came with different solution.

We decided to use existing mechanisms to verify if we can substitute reference in place it has been detected at. We knew that resulting HTML should not change, so we could try substituting local reference with cross-project variation and see if generated HTML is different than the original one. If it didn't change, then substitution is valid.

Below you can find some implementation details of current solution.

1. Match all local references to project, issue, merge request and all other entities using Regexp.

   References like #123 for issue, !456 for merge request are being matched.

2. Substitute each subsequent match with fully-expanded cross-project reference.

   This substitutes reference like #123 with gitlab-org/gitlab-ce#123.

3. For each substitution generate HTML twice, using a new content and using an old content.

   Because of the fact that cross-project reference, when used in a context of the project it refers to is rendered as a local reference, both resulting HTMLs should be the same.

4. If resulting HTMLs are the same, we permanently alter original text to contain cross-project reference instead of local reference.

This solution is not the most optimal one because of performance reasons, but it allowed us to ship this feature quickly and in the future we can improve it by using Abstract Syntax Tree implementation for Markdown.

With this approach, we are also sure that modifications to issue/comments content are correct and don't break your issue which can hold valuable information.