Issue links should have the title

Description

An issue number without a context is not valuable when you have thousands of issues. Having to write it out is a pain.

Proposal

We expand issue titles, but only when they're not followed by text.

If they are, we restrict it to the number with a bit of the text, which can expand on hover.

To allow the old functionality to exist (for when you just need a short id), we can add a new syntax of adding - to the end of the id. For instance #2323-.

Alternatively, this new functionality would be hidden behind a new syntax +, so #2323+, but I prefer to make the default behavior the smarter behavior.

Links / references

cc @markpundsack @regisF

Added feature proposal label

Milestone changed to %Backlog

Related: Show titles on issue mentions - https://gitlab.com/gitlab-org/gitlab-ce/issues/20948

This will definitely be a very welcome improvement, because it is indeed a pain.

Love this.

Related: #20948 (closed) (system notes only (yes please!)) and #20934 (closed) ("chips", (no thanks)).

Depending on your style and habits, this suggestion may or may not be welcome.
I like the idea that the title is not shown when the link is surrounded by text. Still, I often use issue links in tables for meta-issues and alike and can think of several situations where this proposal would be a pain.

Remember that there is a tooltip with the title already.

PS: What about a different syntax for enabling it? For example, #123 for the current behavior and #123+ to include the title in the link? (Of course we could also change the default, but I'd really like to be able to create a short link that only has the ID.)

@pbr I like this last one a lot, although maybe turn it around:

#123 for with description and #123-without description for these pain point situations ;)

https://gitlab.com/gitlab-org/gitlab-ce/issues/20934 has actually converted in the conversation of having the "opened" / "closed" status behind it ;)

@dimitrieh Fine with me. I just see a big risk of feature and UI overkill in GitLab with so many enthusiastic people working on it. I'd just like to remind everyone of the KISS principle

Also, picking up the initial description of this issue:

An issue number without a context is not valuable when you have thousands of issues. Having to write it out is a pain.

When you have less than thousands of issues (let's say we usually have 20-50 open and active issues at a time, which should be realistic for many well-managed mid-size projects), it's a pain to have to use features that are designed for projects with 4000+ open issues. It's a solution to a problem we don't have.

PS: Again, remember the tooltip showing the issue title!

@pbr mmh you are converting me the other way ;) let's keep it at #123+

Added ~14281 label

mentioned in issue #20934 (closed)

mentioned in issue #21364 (closed)

so basically

• #21179 would result in #21179
• #21179+ would result in #21179 Issue links should have the title

So what referring to comments?

this is currently I believe only possible through mentioning the url:

#21179 (comment 14378114)

but what about:

#21179 Issue links should have the title (comment 14378114)

https://gitlab.com/gitlab-org/gitlab-ce/issues/21179#note_14378114+ ?

mentioned in issue #20948 (closed)

@dimitrieh @pbr great ideas. Adding it to the description.

@dimitrieh @pbr I think the proposed behavior is smarter and a better default, so I prefer the - strategy. See the description.

cc @DouweM @stanhu @dzaporozhets @regisF

I like the #4827- idea and the overall concept. However I wonder about the rule concerning issue title truncation #434 blabla → Show.... #434 blabla.

For the sake of simplicity, either we expand the entire Issue title, or we don't. Because this is the only case where we don't actually control the output.

There are two aspect that have not been covered but partially addressed:

• @dimitrieh : I don't think we should mention the comment number (comment 3231311) when expanding the issue title. It does not bring any value to know it's a comment.
• the screenshot above: listing the issue number makes it harder to read. Here is something I suggest (please, UX, make that prettier):

@regisF yeah, I think I agree with you on that. The hover-over state / popup can have the title though.

Something like that mockup could be nice :) @regisF can you update the issue description?

Milestone changed to %8.13

How would this look if the Issue that is in another Group/Project?

Examples:

gitlab-org/gitlab-ce#21179  
gitlab-org/omnibus-gitlab#1081  
gitlab-com/www-gitlab-com#774

gitlab-org/gitlab-ce#21179
omnibus-gitlab#1081 (closed)
gitlab-com/www-gitlab-com#774

@regisF

I don't think we should mention the comment number (comment 3231311) when expanding the issue title. It does not bring any value to know it's a comment.

The thing is, I don't think its possible to refer to an issue comment without an actual URL correct? That is why I made this case:

So the issue here is: do we expand issue titles when we refer to an issue comment by default as well or do we have to alter the url with a + or -?

I however do think that knowing if there is being refered to just an issue or a certain issue comment is valuable information.

---

the screenshot above: listing the issue number makes it harder to read. Here is something I suggest (please, UX, make that prettier):

I tried to make this case in this issue: https://gitlab.com/gitlab-org/gitlab-ce/issues/20934 but was regarded as visual bloat, see comment: https://gitlab.com/gitlab-org/gitlab-ce/issues/20934#note_13878999

point is, if we still introduce some additional flair to issue mentions, we also have to think about MR, commits, builds, and person mentions.

image for possibilities from that issue:

cc: @JobV

Added ~19492 label

Related: #17942 (moved), #20135 (moved) Approximate duplicate of #12927 (closed)

@dimitrieh I think we don't need icons to represent stuff . We just need to have a simple way of making #242322 This is an issue with more readable when we read it.

mentioned in issue #1369 (closed)

@regisF got that ;) just wanted to add my bits an pieces from previous conversations.

to get to the design:

lets get it into the same style as these buttons a little:

like this:

and:

1 px border same color, nice and simple

Reassigned to @dimitrieh

I assigned this to me until we decide on a style ;)

Perhaps it's far fetched, but wouldn't it be confusing to take the same design as a button if it's not a button? Regardless of the solution we choose, as long as we make a visual distinction between issue number and issue title, I'm fine with it :-)

@regisF mmh the more detailed reason is that people already imho already refer to this style as "clickable" as it is used elsewhere throughout the interface. You could see it as a mini button for the whole issue mention so to say. I think its the simplest solution :-)

Plus this way it doesn't collide with "labels"

mentioned in merge request !5993 (closed)

I like simple. Your call!

@tauriedavis @hazelyang what is your opinion :) ?

Duplicate of #17297 Ability to add issue title to text

I think this is just a matter of making our Markdown renderer a bit smarter. @rspeicher, do you see any issues with this?

Can we update the original description with where we are so far?

I love @dimitrieh's design concept from https://gitlab.com/gitlab-org/gitlab-ce/issues/21179#note_14400593 and I'm fine with either the #1234- or #1234+ ideas.

I think it's a bad idea to try to be "smart" about truncating the title when there's other text "near" it. Make the user be explicit in their wanting this expansion.

If we add this feature can we stop adding tooltips to everything too?! Bonus!

What about this one?

#17297 -> #17297 (closed) (current behavior).
##17297 -> #17297 Ability to add issue title to text (new behavior).

@blackst0ne Not a fan, looks like a typo. Thinking about it more, I don't think we should do #1234- either because external references can be JIRA-1234, and the #1234+ makes more sense because we're expanding something.

mentioned in issue #17011 (closed)

For consistency with every other part of the user interface, I suggest using tooltips as implemented in https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5301.

Adding - and + suffixes requires too much work on the part of the author, and the author can't know for sure if the reader will want to know the title, or not.

Rendering it inline will also make it harder to cache Markdown, since the title needs to be inserted into the text at render time. With a tooltip, it's easier to do this in post processing only, like https://gitlab.com/gitlab-org/gitlab-ce/issues/1369.

I would also like to repeat my argument at https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3559#note_11630895 against automatically adding the title in-line, which @rspeicher and @dzaporozhets seconded:

Our references should support the sentence the user is writing, not completely break the flow of it.

To take it to the extreme, when I write this, which is actually not that more extreme in reference use than some of the comments I've written:

I think issue #123 was introduced by 123abc as part of !123 by @zj. It was supposed to fix #234 but because 234def was merged just before !123 was, it didn't work quite as intended. 

I don't want to have it rendered as:

I think issue #123 (closed) (Weird problem that I can't quite explain when you do X and Y at the same time) was introduced by 123abc (Refactor this and change that to fix bug) as part of !123 (closed) (Fix super annoying bug with feature X) by @zj (Zeger-Jan van de Weg). It was supposed to fix #234 (closed) (Super annoying bug with feature X) but because 234def (Refactor feature Y which is used by feature X) was merged just before !123 (closed) (Fix super annoying bug with feature X) was, it didn't work quite as intended.

Which is completely unreadable compared to the original:

I think issue #123 (closed) was introduced by 123abc as part of !123 (closed) by @zj. It was supposed to fix #234 (closed) but because 234def was merged just before !123 (closed) was, it didn't work quite as intended.

I suggest we add tooltips on these references with the issue/MR/commit title. We already have a tooltip on labels, and the references already have a title-attribute, it just isn't displayed as a tooltip.

Just my opinion, but it would be great if we could decrease the use of tooltips. I'm also not sure how accessible tooltips are.

If we add this feature can we stop adding tooltips to everything too?! Bonus!

@rspeicher I think we should also shoot for more descriptions in general so that there isn't that situation where you say: "I have no idea what is going on here without the tooltip". We should never have to rely on tooltips to tell us information we don't have, only to clarify. All the information should be visible to begin with IMHO. Thanks @rspeicher for bringing that up.

Mentioned elsewhere, but I think Trello handles this well. They always expand links to titles, but they're treated well graphically so that they're never confused with the flow of text, which addresses the concerns in https://gitlab.com/gitlab-org/gitlab-ce/issues/21179#note_14443036 (although perhaps not as well as @DouweM would like).

I think @dimitrieh was on to something with the chips, but the treatment might have just been too strong.

mentioned in merge request !5301 (merged)

@DouweM

Even though I get what you mean, your example is not entirely fair ;) the following results would come closer to the truth:

from current situation:

1

to douwe's original:

2

to:

3

or without full user name, which doesn't add to much:

4

with the markup:

5

and say we use the - or + principle this would be the more likely scenario isn't it?:

6

---

Still i think its good to come up with these scenarios. Because this makes me think like, what if we would only do this this "style" if a user actually wants the title to be included (cc: @ClemMakesApps ) :

say the user wanted to expand 2 mentions only:

7

and without any expanded mentioning but with styling:

8

---

the numbers make them easier to discuss ;)

---

if you want to try out this style with a <span> or <a> element:

    border: 1px solid #3084bb;
    border-radius: 3.25px;
    padding: 0 3px;

sidenote: @DouweM closed the following issues in favor of this one which include the conversation of expanding the issue/mention titles in "mentioned in" system messages:

https://gitlab.com/gitlab-org/gitlab-ce/issues/20948#note_14443080 https://gitlab.com/gitlab-org/gitlab-ce/issues/17011#note_14442963

like:

making them into:

which is imo certainly a good idea

I fully agree with @DouweM.

Actually, I don't even see the problem we're trying to solve here. If you write issue descriptions that are not readable without having references automatically being expanded, the problem is your writing style, not the system you are using. Sure, in some situations you might want to point someone to an existing issue by only commenting with an issue number and no further text. But to me, that's the only situation where it actually makes sense to include the title. And that's why I suggested the + syntax.

The button-like references are so dominant that they seriously decrease readability. Why do we need those borders? For the sake of introducing more elements? Why do we then even keep the issue number around at all? Again, please let us keep this simple and not over-design or over-engineer this non-issue.
Any "solution" (again, I don't see the problem in the first place) that introduces elements that might break the reading flow or have a substantial negative impact on the readability (compared to plain text without any highlights or eye candy at all) are unacceptable IMHO.

I think we have to take into mind that the examples shown above in https://gitlab.com/gitlab-org/gitlab-ce/issues/21179#note_14449689 are of the same value as "ipsum lorem" dummy text. Thus more of a visual value than displaying actual context value. In other words its hard to discern the "real" impact from them.

Let's break the actual problem down again:

Does adding the issue title to an issue mention add real value for context purposes.

• What are the usecases?

  • Make a comment easier to discern context-wise by instantly knowing more about the issue mentioned (instead of a seeing just a number).
  • Making it easier to create lists with full issue titles, without having to do this manually (DRY principle)

• What are the usecases against it?

  • The shorter an issue mention is, the more legibility and the flow of reading is left alone.

Secondary is implementation and looks:

• Do we want to always show it by default or with an extra character: +
  • Is it more work for people to have to think about putting a - at the end every time or a + every time for those cases where if not thought about it, it would have added value or created better legibility?
  • @JobV original proposal takes the thinking out of this sort of, as it creates a rule for keeping legibility in check. (I think this is quite a good rule to add on top of the + and - strategy, as long as people can expect/understand it to work like so.. should not become unpredictable)
• Do we want a border/button -ish look?
  • the reason for this is to make the issue number stand out better from the issue title, but can indeed look a bit much based on 8 in https://gitlab.com/gitlab-org/gitlab-ce/issues/21179#note_14449689 (I agree it it kind of disrupt the reading flow) (a possible solution would be an en-dash (slightly wider then hyphen) #123 – This is the Issue Title, which is used in typography to resemble a connection)

---

@pbr in the light of what I have written:

I think the usecases are good enough to establish a user base for this feature imo (there were multiple issues made for this feature by different people). I can see myself using this feature, but in most cases in @JobV implementation (I do not want to think about it every time, it should just work)

Apart from that I think its wise to consider in this decision, accessibility as mentioned before. We are going to improve upon this in the future, so lets think along now.

I agree with your concern for reading flow, which is exactly the reason why I made the examples (1-8), to get some visuals on this. I have mentioned a possible solution above, if people agree that there should be a better

---

Conclusion for now imho:

implementation:

The @JobV version but with + where people really want it and isn't created. (optionally: the - version for times where it is shown automatically but isn't needed)

it will look like this and will drop the border :

#123 This is the Issue Title

or

#123 – This is the Issue Title

So to clearify: in most cases you will just see the current implementation, but this feature will add value in cases where it is wanted, semi automatical with options

Btw when copying a URL to an issue with or without a comment this should have the same functionality in my mind.

with comment:

https://gitlab.com/gitlab-org/gitlab-ce/issues/123#note_123

#123 This is the Issue Title (comment 123)

or

#123 – This is the Issue Title (comment 123)

I agree with @pbr in that I think the borders are too dominating and make it difficult to read. It all blends together and is difficult to scan. Maybe if there is background behind the issue title, that will help. This will cause the other text to jump out a bit more and it is easier to read the comment and skip past the titles if you don't need them.

Example with @DouweM's comment:

Thank you @tauriedavis, that's a great option. Only thing I'd add is that the background should apply to the issue/mr/commit number as well.

fwiw, I'd love to see us come up with a solution that works without the need for - and +.

@rspeicher

Not a fan, looks like a typo. Thinking about it more, I don't think we should do #1234 (closed)- either because external references can be JIRA-1234, and the Tried to add SSH key and got error (#1234 - closed) makes more sense because we're expanding something.

Double # is much simpler to type than # + digits + special character (whatever it is: +, -, etc).
You just need to type twice the same key on your keyboard.
It's about speeding up typing.

@markpundsack

Only thing I'd add is that the background should apply to the issue/mr/commit number as well.

I agree, although it still needs the distinction/connection between the number and the title:

@tauriedavis the question to ask with this as well is, would it mean that normal issue mentions without a title also get a background?

i do think so: (doesn't seem to me to influence reading flow) I basically think this is the best from both worlds.

---

fwiw, I'd love to see us come up with a solution that works without the need for - and +.

basically jobs proposal :) I am for a semi automatic proposal.. jobs suggestion with the option for + and/or -

---

@blackst0ne

I agree to some degree, as it indeed looks like a typo, but you will not see it effectively as it will render the issue out with just one # ... stil in the mindset of typing an issue, and then figuring out if you want to extend it... I am more in favor of of the + / - (also as its extendable both ways.. adding and removing)

@dzaporozhets I think its time to decide upon this somehow or at least get an implementation of this running

I think @tauriedavis's suggestion makes it more bearable comparable to previous design suggestions, but I am still not convinced this "feature" is necessary. For me and my team it would be no less than a regression. Also, I think @DouweM's example text shows how ridiculous this can will get.

@pbr I don't understand why you are agains this feature since it'll be optional. By default there'll be only issue id as a link, but if you want to expand the link by issue title, you'll just need to add one more symbol and that's it!

Yes, I think that works @dimitrieh :)

@tauriedavis @dimitrieh @jschatz1 @DouweM I am against this feature (in any kind of suffix-prefix-whatever syntax. keep it simple). Tooltips should be enough. No need to render whole title. @DouweM and @pbr gave clear reasons why we should not do it. If person is interested in more context they can hover over reference to see title in tooltip.

@dzaporozhets

If person is interested in more context they can hover over reference to see title in tooltip.

By the way, it is not obvious there is a tooltip for an issue link.
A tooltip pops up not so fast as it should be (like one for the comment timing).
So until this issue I didn't event know about that tooltips.

And what about mobile users? How do I see tooltips for issue links using my phone?

By the way, it is not obvious there is a tooltip for an issue link. A tooltip pops up not so fast as it should be

@blackst0ne This is because currently only the title attribute is used. @DouweM suggested to replace them by Bootstrap tooltips (which is actually already done by !5301 (merged)).

@dzaporozhets what about @JobV usecase? (DRY principle?)

Btw i have reopened https://gitlab.com/gitlab-org/gitlab-ce/issues/20948 , as its a different discussion from this issue.

what about Job usecase? (DRY principle?)

@dimitrieh what about it?

@dzaporozhets it mentions the usecase of quickly being able to generate issue numbers with their title for creating better meta issues/lists for example. It was the main point for this issue. If we would introduce just the + feature, nothing will change, except when a user really needs it to.

dry principle, it would automate this process of setting up lists etc a lot for people like job

it mentions the usecase of quickly being able to generate issue numbers with their title for creating better meta issues/lists for example. It was the main point for this issue. If we would introduce just the + feature, nothing will change, except when a user really needs it to.

Just the main point of this issue!

mentioned in issue #12927 (closed)

dry principle, it would automate this process of setting up lists etc a lot for people like job

@dimitrieh For this specific use case, there is another issue: #17942 (moved)

mentioned in issue #17942 (moved)

@winniehell we need the + implementation for https://gitlab.com/gitlab-org/gitlab-ce/issues/20135 as well... it cover an even more advanced version...

mentioned in issue #20135 (moved)

@dimitrieh for lists I commented at https://gitlab.com/gitlab-org/gitlab-ce/issues/17942

Assignee removed

I unassigned myself from this issue for now ;)

mentioned in issue #21959 (closed)

Request to @awhildy Could you search through all related issues mentioned and see which one you would like to go in?

Some good candidates that need management and decision making related to decisions on this issue are:

• https://gitlab.com/gitlab-org/gitlab-ce/issues/17942
• https://gitlab.com/gitlab-org/gitlab-ce/issues/1369

Almost all these issue already had a good amount of discussion and some even have MR's that possibly can be implemented. There should be taken an organized look at these

Mentioned in issue #23177 (moved)

Should this be closed as dupe/in favor of https://gitlab.com/gitlab-org/gitlab-ce/issues/17942? @awhildy

Thanks, @tauriedavis! Good call. Closing this issue in favor of the more specific implementation of #17942 (moved).

Status changed to closed

Mentioned in issue #24074 (closed)

mentioned in issue #27559 (moved)

mentioned in issue #17297 (closed)

I'm not sure it's enough to have this in lists. I made a comment over at https://gitlab.com/gitlab-org/gitlab-ce/issues/17297#note_26552045 about our usecase with non-developers. Even inside a "long text", it would be nice to have the ability to include the full issue title. We have lots of internal projects where people don't use Gitlab every day, which means they do not remember the issue titles based on issue numbers. I struggle with this myself, even though I use Gitlab most days. And I didn't even know about the tool-tip with the full issue title before I read this thread.

My take

I've read most of the issues and discussions around this now, and here is my take on it.

• Do use the #123+ syntax
• Do add an em- or en-dash between the number and title (https://gitlab.com/gitlab-org/gitlab-ce/issues/21179#note_14455730) e.g. #123 – This is the Issue Title
• Do not add a border around the number
• The light background colour looks good, and I think it helps readability
• Very unsure about the automatic behaviour - I think it will get too confusing for most users. And the #123+ syntax is very easy and clear

Is this feature going to be implemented? Is really important to be able to see both the text of an issue and the status. This will allow for having issues that represent list of needed features or that group issues together (is not practical to use labels for that). This way if I want to see how a set of things are going I can look at the master issue and have the view of the status of the many composing issues (with title AND status otherwise is very impractical to go over the tooltip all the times). I, as a user, do not care too much on where and if you place a dash between the number etc. but please implement this feature. Thanks

@gioppoluca It sounds like related issues would help with your use case https://gitlab.com/gitlab-org/gitlab-ee/issues/2001. We are currently working on adding the related issue feature. Note it is an EE feature.

mentioned in issue #29727 (moved)

We have lots of internal projects where people don't use Gitlab every day, which means they do not remember the issue titles based on issue numbers. I struggle with this myself, even though I use Gitlab most days.

Agreed. Surely this is a big win if you're not someone who eats and dreams gitlab.