GitLab's strength is in integration from idea to production. Issue management is a crucial aspect here and with this release, we will start tying this more closely together by introducing native relationships between issues. We are starting with a simple bi-directional relationship between any two issues simply called related issues. You can manage it on the issue page itself. We have also harmonized the related merge requests interface on the issues page.
Design
There us a related issues widget, as shown in the mockups.
Given issue A and issue B. If they are related, then issue B's widget shows issue A. And issue A's widget shows issue B.
The relationship only shows up in the UI if the user has permissions to see both issues.
The relationship is "related", which is a general, two-way relationship. Other types of relationships are outside of the scope of this feature.
You can remove a relationship by clicking the x.
You can add a relationship by:
Autocomplete references for issues in the same project
Manually type any reference (cross-group/project), #123, foo#123, foo/bar#123
Link to issue directly, https://gitlab.com/gitlab-org/gitlab-ce/issues/123
The system note should appear in both issues, with the corresponding issue link, i.e.:
In issue A: @victorwu added #4 as a related issue 2 days ago.
In issue B: @victorwu removed #4 as a related issue 2 days ago.
@smcgivern@tauriedavis : The feature requests regarding epics/parent issues are less strong then wanting relationships between issues. I know there's a lot of discussion about related issues and different types of them. This is my take on the simplest MVP, which is a generic two-way linking of issues. I hijacked @dimitrieh 's mockup because I really like the concept, and I'm calling it a "connections widget". I'm not sure if I'm making up that name. But I like it, and I'm sure the design there is consistent with the merge request widget.
Can you folks take a look. I'm still not certain we should do this immediately. But this seems like the smallest step if we were to take a "native" approach. So I wanted to discuss from that perspective.
There is some UI to establish a relationship between A and B. There is some UI to remove the relationship between A and B.
For the MR closing issues, we calculate that from the Markdown references ('closes #x'), and then cache in the database. The problem is that this is dependent on the viewer - we just do this for the author, but it's possible that they say it closes an issue they can't see, and the issue is merged by someone who can see (and close) that issue. Still, that might be a nice first step, although in issues like the regressions issue, we could have a very busy widget very quickly.
@smcgivern : I envision the relationships to be explicitly managed by the user. Like they have to interact with some UI to add / remove relationships. So this would be different from our existing closes #x set of features. At some point I'd imagine we need to somehow either more differentiated, or harmonize them. But for this MVP, it would be explicitly set relationships. So for the regressions issues case, as long as people don't use this feature, it shouldn't impact them.
Let me update the description to make that more explicit.
: I envision the relationships to be explicitly managed by the user. Like they have to interact with some UI to add / remove relationships.
@victorwu@smcgivern those relationships will be viewable by everyone correct? Which means that if an issue is being made "related" to another issue by a certain user.. if a different user cannot see 1 of those issues.. that relationship will not show up for them...
@smcgivern would we want to say like closes #x => related #x in both the description as well as any comments? Or do you envision this more as a slash command?
Which means that if an issue is being made "related" to another issue by a certain user.. if a different user cannot see 1 of those issues.. that relationship will not show up for them...
Yep!
would we want to say like closes #x => related #x in both the description as well as any comments? Or do you envision this more as a slash command?
I was thinking the former, but I agree with @victorwu that this should be a separate thing initially.
Thanks @dimitrieh for bringing up that permissions point. I updated the description to say that you can only view the relationship if you can view both issues.
@smcgivern : We can re-use permissions for adding/remove relationships right? I'd imagine if you can add/remove a label, you should be allowed to add/remove relationships.
@dimitrieh : My thinking is that this is entirely different from the closes #x mechanism initially. In particular, I anticipate somewhere in the UI you link the current issue you are looking at with another issue. I don't think it should be a slash command, especially since you want immediate visual feedback but the widget and the comment box could be quite far away from each other. (But this last point is more of a design detail that I am open to whatever makes sense.)
So using your mockup, I'd expect the "Connections" widget would have three sections (after we implement this) in a given issue
@dimitrieh : This is scheduled for 9.2. Take a look at the description and feel free to update it to something that makes more sense. In particular, we want to just work on one type of relationship between issues for this first iteration, i.e. "related issues". In the future, we will have blocking issues and subissues.
@dimitrieh : This is for EE Starter . But I assume the design for CE should also be updated as well right? If we are using that new connections widget right?
@smcgivern@jschatz1 : I think this one deserves a quick kickoff, even though it appears straightforward. Earliest next week right? Let me know when you have folks assigned and we can do that.
@dimitrieh : We'll need some clever way to associate and disassociate issues. Let us know if that's no do-able by the start of next week.
@tauriedavis : If @dimitrieh is busy with other things that's okay. Is there anyone else that can work on this? Or if we need to, we can shuffle around and work on other items if it's not feasible.
@victorwu Sorry for derailing a bit, but I see issue relations are marked as EES, I wonder why that is? This seems like an issue that could benefit a team of 1 even? Lets say I write an app where I first need a server before I can create client, that would be a use case?
However as this design will tackle both new (related issues) as well as touch existing UI (related branches and merge requests), we should take a look at how this currently works and how this will work/look in combination with new UI.
Related Merge Requests
Currently related merge requests are shown by having the issue ID be mentioned in the merge request discussion (either description or comments) or having the MR ID be mentioned somewhere in the issue (description or comments).
However feedback from https://gitlab.com/gitlab-org/gitlab-ce/issues/4058 has pointed out that we should look into saving vertical space, thus not placing each related mention of either issue or merge request on a new line.
Currently this is done because we show the description of the merge request behind it + the status + the CI status. My design at https://gitlab.com/gitlab-org/gitlab-ce/issues/2383 shows us a very minimal and text-only way of just putting them on a single inline line. However the needs for that feature are a bit more subtle vs this. The probability of a commit being in more than 2 branches is very low.. This letting them be shown on a single line including the title is possible. We will have to be a bit more thought full here.
@smcgivern I think I already asked this once before in a different issue, but is it right to assume we can see which merge requests close the current issue, which mr's just mention the issue but do not close it and which mr's are mentioned somewhere within the issue's discussion? (so this shouldn't be to much of a technical challenge)
I ask this, because I would like to display these Merge Requests differently, effectively creating another category:
Merge requests which will close this issue (by writing Closes #1234 in the merge requests specifically)
Related merge requests (just mentioned in either discussion of isssue or mr)
I want to do this, as I think it will stay important showing these merge request titles of merge requests which will actually close this issue. Also I would just like to see immediately which MR will close this particular issue i am looking at. (agreed here @tauriedavis )
So this will result in the following sections:
Related issues
Related merge requests which close the current issue
Related merge requests which do not close the current issue
Related branches are associated to the issue only by having a name that starts with the internal id of the issue. After using the "New branch" button a related branch will be shown in the issue, but this is only because the branch name starts with the internal ID. You can force an issue to show related branches without using the "New branch" button.
and look like this:
@smcgivern I want to verify if this feature is actually working as it should be. I ask this as I know plenty of cases where I have the issue ID in the branch, while it doesn't show up in the issue. See for example this issue https://gitlab.com/gitlab-org/gitlab-ce/issues/25011
As for the design: In the commit view widget we already have a way of showing branches (although i think that could be optimised):
I think we can take some points from that.. as it tries to show branches as a sort of mini object within that UI... By showing it with a small background.. similar to a tag a bit. This brings us a bit to my next point/section
Design of showing object view links (issues, merge requests, pipelines, jobs, branches) in non-inline text UI's
I would like to begin showing links to object views, while not inline in text bodies, as more of an "object". We already began this move with the status badges in the pipeline list for example.. (we have both the pipeline status, as well as the ID to click on to get to the same page.. we could improve there imo.. with this same direction)
If we'd combine this with status, we can come to the design below. (See how you like this @tauriedavis or you rather just want a text based version.. we'd still have to see how we'd handle badges and ci statuses, this design handles all that )
A last small note regarding merge request statuses, is that it doesn't make a lot of sense to show the overall pipeline status in this list when the merge request has already been merged (correct @markpundsack ?)
Order of showing
My last section is on order of showing. I think the following order makes the most sense in order of importance:
Related merge requests which close the current issue
Related merge requests which do not close the current issue
Thanks @dimitrieh - I think we can start with a more simplified version and not worry about the CI status. Having the status icon and the CI icon looks confusing to me and visually there is a lot going on. I'm entirely sure the CI information is necessary for every view on the site and I think issues is somewhere we can not include it.
I skimmed through the related issue about inline vs. showing the title. Maybe we can give an option to expand/collapse the title. In your example above, the closing MRs have titles but the rest don't. Visually I think it would help to keep the sections the same - expanded or collapsed.
We haven't addressed how the user will add a related issue. The easiest option I think would be to add a section to the edit section of an issue that allows you to add a related issue by pasting the URL.
Are we allowing related issues only within the same project? If so, we would need to throw an error if someone tries to link an issue from outside of the project. Alternatively, we could allow the user to add an issue from any project and pre-fix the issue number with the group/project name.
I'm unsure if this is out of scope. We could also limit adding related issues to just slash commands if thats easier for the first version.
Scope-wise, let's focus just on related issues itself. Let's have the widget just contain the related issues for this feature. If we have time in this milestone, we can tackle putting in the other sections too. But we should get related issues only merged into master before doing that.
Agree with the CI status. That's definitely future enhancements. A simple issue id with status and link to it is definitely enough. Issue title and on hover info are bonuses. But not much more than that I would say.
Definitely in my estimation the most complex part is adding and deleting related issues. Let's make sure we nail that. Can we add / remove related issues using some AJAX-style UI? We want to move away from the web form and do edits inline right? E.g. https://gitlab.com/gitlab-org/gitlab-ce/issues/25052.
Yeah, we do want to move away from the web form - I wasn't sure if that would be out of scope for this feature right now. It would be great to add/remove inline if that something we can get into 9.2. Will update the mockups with that direction.
I can see how managing blocking relationships might integrate with the burn down chart for EE, but what is the reasoning for limiting general issue relationship management to EE? Sub-issues is a highly requested CE feature that probably needs this groundwork.
Thanks @deckar01 . It's not clear whether subissues should be CE or EE at this point. You're right this feature is a building block to more advanced EE features. If or when we build any CE features that use this building block, we'll make the decision then to see whether to bring Related Issues to CE itself. Thanks!
I think we can start with a more simplified version and not worry about the CI status. I'm not entirely sure the CI information is necessary for every view on the site and I think issues is somewhere we can not include it.
I agree here ;)
We haven't addressed how the user will add a related issue. The easiest option I think would be to add a section to the edit section of an issue that allows you to add a related issue by pasting the URL.
I am afraid that this would make the feature not as visible or as easy to use as it should be. Slash commands seem much more reasonable to me.. especially as a bonus towards inline editing. Currently we write: related to #ID .. slash commands approach this very similarly and we'd need a proper system note to go along with it:
i am not a big fan of the big header.. why waste that much vertical space.. let's use the same dimensions as the mr widget uses in the new design: 45px if we need a header at all... In the merge request widget the header/title changes dynamically. With this widget it would be a static "relationships".. I think the content speaks for itself, not? :)
Although i think the header does make the widget stand out a little better.. and makes room for the button
Scope-wise, let's focus just on related issues itself. Let's have the widget just contain the related issues for this feature. If we have time in this milestone, we can tackle putting in the other sections too. But we should get related issues only merged into master before doing that.
@victorwu I do not agree here . I know we are aiming for mvp's. The absolute minimum we can do to get something in. However imo that does not mean creating a mess by setting the bar at the lowest. We have related/existing UI that should be conformed to the new style we are trying to achieve here.. at the very least we should get some technical perspective on the achievability of this (what exactly is the extra effort) @smcgivern
To decrease the scope and get to the absolute mvp.. we can perhaps do some other things, compared to the previous designs:
@dimitrieh Minor detail, should we differentiate the issues the current issue is referencing from other issues referencing the current issue? On the design we show all issues as "editable", but there will be the case when the current issue is added as related elsewhere, so we should also present it on the current issue. The question is, should them be presented on a second line? Or just not showing them as editable would be enough?
Slash commands are great. But as always, there's the problem of discoverability, and you would need to scroll to the bottom of the issue and type in the comment box to use it. So you wouldn't be able to interact with related issues in the description area directly.
Thanks @dimitrieh for the designs. They are an improvement for sure. I'm not sure about the copy, though "Mention the related issues just as in comments." Is this needed? Maybe "Link to related issues using the URL or GitLab Special Reference."
Agree with @victorwu about slash commands. Will we be including them in this release as a secondary way?
So you wouldn't be able to interact with related issues in the description area directly.
@victorwu@tauriedavis i thought of it as 2 ways to edit the same.. so we can edit in the issue description and have the slash commands while you are at the bottom of the discussion (where you can see the system note appear).
Minor detail, should we differentiate the issues the current issue is referencing from other issues referencing the current issue?
@oswaldo this was in the scope of the issue: "Given issue A and issue B. If they are related, then issue B's connections widget shows issue A. And issue A's connections widget shows issue B."
@smcgivern I think I already asked this once before in a different issue, but is it right to assume we can see which merge requests close the current issue, which mr's just mention the issue but do not close it and which mr's are mentioned somewhere within the issue's discussion? (so this shouldn't be to much of a technical challenge)
We can't distinguish the last two. The only reason we see MRs that just mention the issue is because that creates a cross-reference note in the issue, and we extract the MR from that. We can distinguish between MRs that close the issue and those that don't, though, which I think does what you need!
@smcgivern I want to verify if this feature is actually working as it should be. I ask this as I know plenty of cases where I have the issue ID in the branch, while it doesn't show up in the issue. See for example this issue https://gitlab.com/gitlab-org/gitlab-ce/issues/25011
Please create a bug for that, we don't need to discuss it here
My initial BE proposal is quite simple, a new table storing an Issue assignee_id, an assigned_id and something like a relation_kind (which would store related, blocking, etc) with the type of relation.
That should be enough to:
Present Issues the current issue assigned as related
Present Issues the current issue was assigned as related
Appropriately separate by relation types (future?)
Appropriately filter unauthorized Issues
Obs.: We could also have a type on this and re-use in the future for Merge Request relations.
@oswaldoassignee normally refers to a user, wouldn't we just want a table with two issue IDs? I don't know what we'd call them; perhaps issue_id and related_issue_id?
Also, the kind is out of scope for the moment, but thanks for thinking of it I think the design apart from those two points is reasonable!
For MR relations, we already have a merge_request_closing_issues table. I think we should try to use foreign keys as much as possible, so instead of a type field, we could have a separate table for MRs, or add a merge_request_id and related_merge_request_id column. Wdyt?
assignee normally refers to a user, wouldn't we just want a table with two issue IDs? I don't know what we'd call them; perhaps issue_id and related_issue_id?
Sounds great to me! Indeed, assignee always refers to Users.
For MR relations, we already have a merge_request_closing_issues table. I think we should try to use foreign keys as much as possible, so instead of a type field, we could have a separate table for MRs, or add a merge_request_id and related_merge_request_id column.
I took an extra step there since we'll focus solely on Issue relations on Issue page
But sounds good to me on having a new table for the MR relations (having performance as priority). Anyway, this also seems to be out of scope for this iteration, correct?
I think it should work like that, cross project (not just limited to group.. say you only have private projects for example). Also as we will use this syntax as input:
Let me know when I missed details and I will be ready to get to you! I will be off and on next week.. (See availability calendar) if so please ask someone from the UX team
@oswaldo@MadLittleMods : For this issue, please only work on the new functionality with the new widget design, i.e. related issues. Please complete and merge this work into master, before working on extending the design on the existing related branches and related merge requests UI into the widget. That should be worked on after and that is in a separate issue here: https://gitlab.com/gitlab-org/gitlab-ce/issues/31123. I've made that 9.2 stretch.
I've updated the description here to reflect the scope. Thanks.
Thanks @JobV for the feedback. I agree we can make the experience even better. That said, I see some issues with the wireframe you proposed.
Remove icon visible on hover is not mobile friendly.
Entering to save an input field is unintuitive and doesn't give confidence to the user that their action is saved. It works in instances such as search, where the action isn't something that persists over time.
I've worked on a second version that includes:
A way to remove related issues immediately. My assumption is that there is a low risk factor here, esp if we include system notes like shown at the bottom of the mockup. If there are mistakes, we may want to make close available only in some edit state.
Each issue shows status, special reference, and title while being displayed inline to take up less space
You can add related issues in the same way that you add an issue to the issue board
The user is able to add multiple related issues at one time
The user can search for a related issue using the title, special reference, or by entering the URL
The user has confidence that there action is being performed by the inclusion of a save button
@victorwu Were the designs removed from the description in place of @JobV's wireframe?
@MadLittleMods i think it may be best to save as much vertical space as possible here, but offer the option for further explanation through a help questionmark icon leading to some documentation. @axil do or will we have documentation on this feature?
@dimitrieh@tauriedavis : Is it possible to use our existing style of empty states (a nice image) but use a version that doesn't waste too much vertical space.
@MadLittleMods : I updated the description. Please update it if anything is incorrect. We're working backwards a bit here because most of the dev work is already done I think?