Formalize what we support for references to external issues [meta]

External issue reference pattern

External issue reference pattern is never formally specified in our documentation. From the code perspective we have:

1. https://gitlab.com/gitlab-org/gitlab-ce/blob/78ee24ba53a4a44d829613495ec0d5f1bbb5a9ee/app/models/project_services/issue_tracker_service.rb#L9 - for Redmine, Bugzilla and custom issue tracker integrations. This regex also allows references such as #123.
2. https://gitlab.com/gitlab-org/gitlab-ce/blob/78ee24ba53a4a44d829613495ec0d5f1bbb5a9ee/app/models/project_services/jira_service.rb#L22 - for JIRA

I found some evidence that #123 format is expected by the users. See https://gitlab.com/gitlab-org/gitlab-ce/issues/18827#note_12568147 where a user expresses a concern that this feature is now broken and we commit to fixing it (which we did).

Referencing internal issues in other projects from projects with external issue tracker enabled

Internal issues in other projects can still be referenced when a project has an external issue tracker, for example from merge request comments. This should just work (TM). But it doesn't:

1. https://gitlab.com/gitlab-org/gitlab-ce/issues/33679 [confidential]
2. https://gitlab.com/gitlab-org/gitlab-ce/issues/34076
3. gitlab-foss#34446 (moved)

Referencing external issues in other projects

I didn't find any mention of this in the documentation, nor any explicit trace in the codebase. In fact, for JIRA integration we don't even know how such a reference should look like. If a reference to a current project is DEVOPS-3 then the reference to another project should be namespace/project-nameDEVOPS-3. As you can see we are clearly missing a separator here.

That said, it is possible if we use #1234 format (discussed in the "External issue reference pattern" section), for example for Redmine. This partially works, see https://gitlab.com/gitlab-org/gitlab-ce/issues/34082. However, this may be a totally accidental feature.

Technical debt

We have Banzai::Filter::IssueReferenceFilter and Banzai::Filter::ExternalIssueReferenceFilter. Banzai::Filter::IssueReferenceFilter is responsible both for managing references to internal issues and references to external issues. The role of Banzai::Filter::ExternalIssueReferenceFilter is unclear to me, there is a chance that it's never used currently. I consider this as a technical debt and main source of bugs in this area from the code perspective.

Relevant bits of documentation

Feel free to add more!

1. https://docs.gitlab.com/ce/user/markdown.html#special-gitlab-references
2. https://docs.gitlab.com/ce/user/project/issues/crosslinking_issues.html
3. https://docs.gitlab.com/ce/user/project/integrations/redmine.html
4. https://docs.gitlab.com/ce/user/project/integrations/jira.html
5. https://docs.gitlab.com/ce/user/project/integrations/bugzilla.html
6. https://docs.gitlab.com/ce/integration/external-issue-tracker.html

mentioned in issue gitlab-foss#33097 (closed)

changed the description

changed the description

mentioned in issue gitlab-foss#34082 (closed)

changed the description

added docs-missing in GitLab FOSS label

/cc @smcgivern @victorwu

/cc @jarka

mentioned in issue gitlab-foss#33679 (closed)

changed milestone to %Next 2-3 months in gitlab-foss

Already mentioned this in https://gitlab.com/gitlab-org/gitlab-ce/issues/34082#note_33163226.

Let me propose more fully:

• GitLab Project A is integrated with External Tracker E in Project A's integration settings.
• GitLab Project B is integrated with External Tracker F in Project B's integration settings.
• In any issue, merge request, etc. of Project A:
  • You can refer/link to Project B's issues, merge requests, etc.
  • You can refer/link to E.
  • You cannot refer/link to F.

Do we have to worry about ambiguity when multiple issue trackers are turned on?

@adamniedzielski thanks, that's a great investigation

@victorwu I think we do, I don't think that's well-defined at the moment either. My guess is that the people who expect this to work have the simplest case: a single external issue tracker enabled, and the internal tracker disabled.

So maybe we only support the 'shorthand' form (#123) in that case. Then for cases where multiple issue trackers (of any type) are enabled, #123 refers only to GitLab issues, and the 'long' form (REDMINE-123) is required for all external trackers.

For cross-project references, as I've said before, I don't believe that these make sense for external trackers (because a GitLab project does not necessarily map to a 'project' in the external tracker, and in the case of JIRA specifically, you can reference multiple JIRA projects from a single GitLab project anyway). So I'd like to explicitly forbid that if we can.

I agree, I'd like to explicitly state that we don't support cross-project references for external issue trackers. This will hopefully allow us to simplify the code and solve gitlab-foss#34082 (closed).

Just to clarify: right now we don't support multiple external issue trackers. See https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9669. One caveat: this validation was not enforced for existing projects, so there may exist projects with two issue trackers enabled.

@smcgivern I like your proposal. It can be expressed as these two rules:

1. Links to internal issues should be extracted before links to external issues (should have priority). So #123 refers to internal issue
2. When the internal issue tracker is disabled we don't extract links to internal issues for current project. We still extract cross-project links.

This allows people who rely on the "shorthand" form for an external issue tracker can still use it, after disabling the internal issue tracker.

@adamniedzielski also rule 3 from https://gitlab.com/gitlab-org/gitlab-ce/issues/34070#note_33229748!

• We only extract cross-project references for the internal issue tracker on the target project.

But yes, I'm happy with that

mentioned in merge request gitlab-foss!12485 (merged)

changed the description

moved from gitlab-foss#34070 (moved)