crosslinking_issues.md 2.36 KB
Newer Older
Marcia Ramos's avatar
Marcia Ramos committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
# Crosslinking Issues

Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.

## From Commit Messages

Every time you mention an issue in your commit message, you're creating
a relationship between the two stages of the development workflow: the
issue itself and the first commit related to that issue.

If the issue and the code you're committing are both in the same project,
you simply add `#xxx` to the commit message, where `xxx` is the issue number.
If they are not in the same project, you can add the full URL to the issue
(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`).

```shell
git commit -m "this is my commit message. Ref #xxx"
```

or

```shell
git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>"
```

Of course, you can replace `gitlab.com` with the URL of your own GitLab instance.

28
NOTE: **Note:** Linking your first commit to your issue is going to be relevant
Marcel Amirault's avatar
Marcel Amirault committed
29
for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/stages-devops-lifecycle/cycle-analytics/).
Marcia Ramos's avatar
Marcia Ramos committed
30 31 32 33 34 35 36
It will measure the time taken for planning the implementation of that issue,
which is the time between creating an issue and making the first commit.

## From Related Issues

Mentioning related issues in merge requests and other issues is useful
for your team members and collaborators to know that there are opened
37
issues regarding the same topic.
Marcia Ramos's avatar
Marcia Ramos committed
38

39
You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages).
Marcia Ramos's avatar
Marcia Ramos committed
40

41 42 43
When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification
in its tracker. That is, you only need to mention the relationship once for it to
display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests).
Marcia Ramos's avatar
Marcia Ramos committed
44 45 46 47 48

![issue mentioned in issue](img/mention_in_issue.png)

## From Merge Requests

49
Mentioning issues in merge request comments works exactly the same way as
50
they do for [related issues](#from-related-issues).
Marcia Ramos's avatar
Marcia Ramos committed
51

52 53
When you mention an issue in a merge request description, it will simply
[link the issue and merge request together](#from-related-issues). Additionally,
54 55
you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically)
as soon as the merge request is merged.
Marcia Ramos's avatar
Marcia Ramos committed
56 57

![issue mentioned in MR](img/mention_in_merge_request.png)