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)
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] |
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?
Yes, this affects every stage that wants to have easily referenced objects.