Extensible reference filters

Problem to solve

We are running out of ASCII characters to use as prefixes in reference filter short-codes. We already use ~!@#$%& and are thinking of assigning ^ to designs.

Short codes are great, and some (such as # and @) are almost ubiquitous in usage across platforms. They make for an excellent autocomplete experience.

However, there are lots of different kinds of objects in GitLab, and it is not unreasonable to want to reference them too, but when we run out of the top row ASCII characters, that is going to hurt.

Current character assignments (See GitLab Markdown docs ):

~ Label
! Merge Requests
@ User
# Issue
$ Snippet
% Milestone
& Epic

Intended users

This benefits all users, since all users are expected to read and write text on the platform.

User experience goal

We can freely add new reference filters without having to approach APL level text-salad, and while remaining clear what each reference does.

Proposal

We introduce a text-based syntax, with an easily parsed prefix, capable of extension

Other options we explored:

1. Handlebars

Use {{$name:$args}}:

Can we move {{issue:123}} to {{milestone:1.1}}? I know it is part of {{epic:2}}
but it seems separate? I don't think it is {{label:workflow::in dev}} though!

Also, what about {{issue:some-group/proj-a/123}} and {{issue:some-group/proj-b/123}}? Should
we add them as well?

This would allow us to detect prefixes such as {{user: and dispatch to a user autocomplete.

2. Single character prefix

Use ^<filter-name>#<reference-content>, since this has already been implemented for some of our reference types.

Can we move ^issue#123 to ^milestone#1.1? I know it is part of ^epic#2
but it seems separate? I don't think it is ^label#"workflow::in dev" though!

Also, what about ^issue#some-group/proj-a/123 and ^issue#some-group/proj-b/123? Should
we add them as well?

And should we split ^vulnerability#929 into its own issue?  I see ^vuln#some-group/proj-c/323 
is the same, so maybe do them at the same time.

3. Use MDX

This embeds XML-elements with custom semantics:

Can we move <Issue iid="123"> to <Milestone title="1.1">? I know it is part of <Epic iid="2">
but it seems separate? I don't think it is <Label title="workflow::in dev"> though!

Also, what about <Issue path="some-group/proj-a" iid="123"/> and <Issue path="some-group/proj-b" iid="123"/> Should
we add them as well?

This has the benefit of being an existing standard with known escaping rules.

Use markdown references

Markdown already has built-in references, using the syntax [issue:45119]. So it's a familiar syntax and visually looks like other links. Discussion thread

Can we move [issue:123] to [milestone:1.1]? I know it is part of [epic:2]
but it seems separate? I don't think it is [label:workflow::in dev] though!

Also, what about [issue:some-group/proj-a/123] and [issue:some-group/proj-b/123]? Should
we add them as well?

And should we split [vulnerability:929] into its own issue?  I see [vuln:some-group/proj-c/323]
is the same, so maybe do them at the same time.

This is similar to Trac syntax

Proposed reference table (using markdown reference link style)

discussion

references	input	cross-project reference	shortcut within same namespace
specific user	`@user_name` `[user:username]`
specific group	`@group_name` `[user:group_name]`
entire team	`@all` `[user:all]`
project	`namespace/project>` `[project:namespace/project]`
issue	`#123` `[issue:123]`	`namespace/project#123` `[issue:namespace/project/123]`	`project#123` `[issue:project/123]`
merge request	`!123` `[mr:123]`	`namespace/project!123` `[mr:namespace/project/123]`	`project!123` `[mr:project/123]`
snippet	`$123` `[snippet:123]`	`namespace/project$123` `[snippet:namespace/project/123]`	`project$123` `[snippet:project/123]`
epic (ULTIMATE)	`&123` `[epic:123]`	`group1/subgroup&123` `[epic:group1/subgroup/123]`
label by ID	`~123` `[label:123]`	`namespace/project~123` `[label:namespace/project/123]`	`project~123` `[label:project/123]`
one-word label by name	`~bug` `[label:bug]`	`namespace/project~bug` `[label:namespace/project/bug]`	`project~bug` `[label:project/bug]`
multi-word label by name	`~"feature request"` `[label:feature request]` (when no escaping needed) `[label:"feature request"]` (can optionally always escape)	`namespace/project~"feature request"` `[label:namespace/project/"feature request"]`	`project~"feature request"` `[label:project/"feature request"]`
scoped label by name	`~"priority::high"` `[label:"priority::high"]`	`namespace/project~"priority::high"` `[label:namespace/project/"priority::high"]`	`project~"priority::high"` `[label:project/"priority::high"]`
project milestone by ID	`%123` `[milestone:123]`	`namespace/project%123` `[milestone:namespace/project/123]`	`project%123` `[milestone:project/123]`
one-word milestone by name	`%v1.23` `[milestone:v1.23]`	`namespace/project%v1.23` `[milestone:namespace/project/v1.23]`	`project%v1.23` `[milestone:project/v1.23]`
multi-word milestone by name	`%"release candidate"` `[milestone:"release candidate"]`	`namespace/project%"release candidate"` `[milestone:namespace/project/"release candidate"]`	`project%"release candidate"` `[milestone:project/"release candidate"]`
specific commit	`9ba12248` `[commit:9ba12248]`	`namespace/project@9ba12248` `[commit:namespace/project/9ba12248]`	`project@9ba12248` `[commit:project/9ba12248]`
commit range comparison	`9ba12248...b19a04f5` `[commit:9ba12248...b19a04f5]`	`namespace/project@9ba12248...b19a04f5` `[commit:namespace/project/9ba12248...b19a04f5]`	`project@9ba12248...b19a04f5` `[commit:project/9ba12248...b19a04f5]`
repository file references	`[README](doc/README)`
repository file line references	`[README](doc/README#L13)`
alert	`^alert#123` (to be deprecated?) `[alert:123]`	`namespace/project#123` `[alert:namespace/project/123]`	`project#123` `[alert:project#123]`
vulnerability (proposed)	`[vulnerability:123]`	`[vulnerability:namespace/project/123]`	`[vulnerability:project/123]`
feature flag references	`[feature_flag:1234]`	`[feature_flag:namespace/project/123]`	`[feature_flag:project/123]`

Extensible reference filters

Problem to solve

Intended users

User experience goal

Proposal

1. Handlebars

2. Single character prefix

3. Use MDX

Use markdown references

Further details

Permissions and Security

Documentation

Availability & Testing

What does success look like, and how can we measure that?

What is the type of buyer?

Is this a cross-stage feature?

Links / references