Automatic display of the issue title is a bad idea

[kparkov]

Very recently the markdown render changed, so that any issue reference by its number (ie. #3888) will be automatically augmented with the title in preview / render mode. This is true for issues and PRs.

While I get the sentiment, it has the very negative consequence that I can either choose to not include the title in the raw markdown, or include it and have it rendered twice in the rendered.

This is a problem, for instance, when I am writing the text for a release PR, and I am summarizing all the things that have been solved in that release. Here, I want to include the title, because I want it to be readable outside Github and in raw text as well.

I am writing it like this:

But unfortunately, then it ends up like this:

I think it is important to note that markdown is a format that should be usable in both raw and rendered format, and I think this change acts counterproductive to that.

[CyberShadow]

Agreed, things expanding to what is possibly an entire sentence while already in the middle of a sentence is not great either. This makes sense if the issue number is on a line of its own or a list item of its own, but not in the middle of a paragraph.

[fantasai]

Even just scaling back to “link is the first thing in the list item” would solve the problem. I can see a use case for expanded titles followed by descriptive text... but not for expanded titles in running text.

[dgw]

This change completely breaks all of our existing task lists, rendering them a jumbled mess of sometimes-redundant words. Issues that are months or years old (long-term tracking kind of stuff over several major versions) get hit especially hard. This is one of the simpler ones:

This behavior should be opt-in via new syntax, rather than blanket-enabling it on all existing Markdown content. Our project works very hard not to change anything (new settings, plugin API features, etc.) that will result in different behavior without user action, and I would expect GitHub—a project and business with hundreds or thousands as many users as we have, to be even more careful.

Don't get me wrong: This is a very welcome feature when it's appropriate to the context! I love being able to create task lists of just issue/PR numbers and having the status & title filled in automatically. It's just that right now we have no way to opt-out even retroactively in cases where it makes our existing task lists messy or unreadable, let alone the fact that this feels like a new feature that should come with its own semantics distinct from the existing "bare" issue/PR number references.

[danishin]

I agree. Having feature as an option is nice but please don't force it on every repo. Would it be possible to have an option to turn this on and off? Some repos will suffer greatly depending on their previous workflow. Please consider.

[felixfbecker]

To provide a counter point, I really like the expansion, even if some of our old issues look a bit odd with it. It's been fantastic for new issues, without needing to re-teach anyone how to reference issues so they get expanded.

[kparkov]

I do agree that it is a nice feature, I just don't like that it breaks the basic contract that raw Markdown should be roughly as readable and complete as the rendered version.

[dwhswenson]

To illustrate another problem (also related to release PRs): I frequently summarize a series of related minor issues in a single bullet point with links to all relevant PRs (e.g., updates to documentation; changes in CI). The previous render (as still seen in the release notes) gives a clean, readable display, which allows me to highlight PRs from external contributors while still making it clear how they fall under the same topic, and emphasizing the topic:

The results of the current render:

The old render allowed me to intentionally hide the irrelevant details behind a PR number, knowing that readers could hover/click on the PR to see details. I find the new render to be much less readable.

[felixfbecker]

I discovered that issues are not expanded when you link them with a full link:

[#923](https://github.com/your/repo/issues/923)

Meaning you still have control over how they are rendered if you're willing to do the effort, just the "default rendering" is changed 🙂 Maybe this helps.

[dwhswenson]

@felixfbecker : This is a good point, and useful information. So today I'm editing the code that drafts my release notes before starting to do the planned release. Fortunately, our workflow copies the Markdown from our release PR to into the notes for the release itself. So as long as the renderer for release notes stays the same, our old releases are still readable. But anyone who relies on a link to the PR still has a headache for existing PRs.

[skipjack]

Kind of annoying to write the whole thing out though, the shortcut was nice and then the tooltip card on hover was a great addition but I kind of wish it stopped there. Or, as suggested above, a new syntax introduced to optionally expand it if desired.

[zadjii-msft]

I'm of two minds on this. In general, it seems like the sentiment is that where there's other text on the line with the issue number, the title shouldn't get unfurled. Maybe there's a more nuanced way to get the same effect?

I really like it in some cases, like when I've got older sub-tasks that had PRs added to the bullet point:

But then there are cases where I've already gone through and copy/pasted the full issue title, resulting in duplicated text:

Maybe there's a way to be smart about when to expand the title and when not to? Like perhaps if the text of the title is already in the bullet point, then replace that text with the unfurled hyperlink and icon. Though dwhswenson's point does seem to be a valid case where that heuristic wouldn't work.

I do like the new rendering more than our old style of copy-pasting titles, but this just means all our old task lists need to get de-duped (when this feature rolls out to the general public). Until it does, we'll still need to keep copy-pasting titles, so we don't just have long lists of

• #‍1
• #‍2
• etc

for users that aren't opted-in yet.

[borekb]

I also see title unfurling as a controversial change – I see its usefulness but it also causes quite some issues:

• The rendering inside issues and pull requests is now vastly different from other places, like *.md documents in the repo, wikis, external services etc. Converting #123 into a link is a useful feature of github.com but it didn't "harm" the other places. With the new rendering, I have to be much more careful – what seems like a nicely readable task list on github.com will be a bunch of "useless" #... references outside of GitHub (or even inside it, depending on situation).
• To "fix" the above, we'll probably keep copying the title manually, leading to strange rendering as in Automatic display of the issue title is a bad idea #4321 (comment).
• Automatically unfurled titles are not indexed for search – I see the word "xyz" in the tracking issue but searching for it doesn't find it. That's confusing but maybe "correct"?!
• It used to be very clear what is a link to an issue vs. the link to a comment – the rendering was #123 vs. #123 (comment). This is now less clear so in our case, it's harder to see which task list item links to a finished issue (a full reference) vs. just its status update that we posted as a comment.

I wonder is title unfurling could be a sidebar option, sort of like in a PR I can choose between side-by-side and unified diffs. That would mean that it's a user option, not a repo setting or some hint inside the Markdown text itself.

I would understand though if you didn't want to make it user-configurable. There are already many "IFs" around how a simple #123 text will render and this would add another one. Still, I sometimes like it, sometimes don't so the ability to toggle it sort of makes sense to me.

[Lucaffo]

I agree, kinda related to my issue i guess.
This feature broke anything have a title and a description in github i guess.

It's a broken feature lol.

#4557

[tpak]

I like the fix proposed in the opening of the old isaacs repo isaacs/github#1020

Currently, the syntax #123 creates an issue link.
Hovering reveals the issue title. But the title is not displayed in the text.

I propose a new syntax, e.g. #123+ that will also display the issue title.

This would give us the best of both worlds - the ability to display meaningful descriptions but also control the chaos created by the current implementation.

[aaronsteers]

This also matches what Gitlab does now. The suffixed + causes auto-expansion, so it's an easy opt-in behavior.

[zekeuribe]

Completely agree, this would be the best implementation that allows for flexibility of when to/not display the full title. The current implementation is very confusing, even for those on my team that have been using GitHub for years.

[fgnievinski]

I've created a separate community discussion, please upvote it if you'd like to have #123+:
https://github.com/orgs/community/discussions/41837

[ptsefton]

Current expansion is inconsistent - it works in issues but not in milestones. I want to be able to reference issues in the milestone description - they are not expanding at the moment.

[drok]

Also doesn't work in release notes, where default expansion using some heuristic makes sense (either issue reference on a line by itself, or with a + suffix)

[talksik]

hello? simple frontend team + product manager adjustment no?