I need to be able to map out dependencies between different issues and epics,
So that I can plan my effort properly through a solid understanding of what sequence the work needs to happen in and what can be done in parallel.
More Details
Currently we allow users to mark issues as "Related to.." another issue. While this is helpful, it doesn't inform me HOW the item is related. Is it related because it's in the same section of code? because it is similar work to effort happening on another section of the product? etc...
To properly enable users to map out dependencies and effort sequencing, they need to be able to mark items as dependent on another item, or that an item is blocking another item of work.
Proposal
MVC: We add 2 additional areas to the issue and epic view, in the same area as "Related to:"
Blocks...
Is Blocked by...
We also add some form of visual representation to show the above two states.
Blocked by, Blocks and Related To should all be accessible via the API
Documentation
Documentation would need to be created for this feature.
Acceptance Criteria
The behavior in the proposal is working.
Necessary tests added.
Uses GraphQL first.
Necessary updates to public GraphQL and REST APIs.
Telemetry exists to assess feature adoption
Documentation added.
Pajamas first. If major changes are required for the graph, consider contributing to the unified dashboard project.
Solution
We are expanding the functionality of the existing Related Issues component by including the ability for users to establish a relationship between issues in one of the following 3 ways:
blocking
blocked by
related to
More than one issue can be added at a time and once added, will display in a newly segmented list below with the same 3 categories.
By default related option should be used (both for existing and new relations).
Feature flag name:issue_link_types
0 of 7 checklist items completed
· Edited by
Donald Cook
Designs
An error occurred while loading designs. Please try again.
Child items
0
Show closed items
GraphQL error: The resource that you are attempting to access does not exist or you don't have permission to perform this action
Could this be slightly expanded to also block merge requests from merging (through the gui) when there are blocking issues (other merge requests); it shouldn't take much longer then implementing the original scope
@jonas1 : Yes I think so. We might actually need to include that, depending on the implementation, becasue of auto-closing. I.e. we can't claim "blocking" if it doesn't block auto-closing mechanisms. I'll update the issue accordingly. Thanks!
@victorwu I'm not sure that covers @jonas1's request, which is to prevent an MR from being merged. (My personal opinion is that this shouldn't be in the first iteration - there are already lots of ways to prevent an MR being merged, and the relationships we have are only between issues.)
If Issue A is open, Issue B cannot be closed. Issue B can be deleted.
I assume that if issue A is closed, then issue B is closed, then issue A is reopened - issue B is not automatically reopened?
Similarly, if issue B is already closed when it is set as being blocked by issue A, it can be reopened, but it can't be closed if it's then reopened until issue A is closed?
Update the merge request text copy to say, "Attempts to close Issue B".
This needs an extra line:
Issues that will be closed.
Issues that are mentioned but will not be closed.
Issues that would be closed, but currently can't be because they are blocked.
Is that worth it for the first iteration?
When the merge request is merged, suppose Issue A is open, then Issue B remains open.
The merge request says text copy says, "Issue B was not closed".
We don't actually move this to past tense at the moment. Doing so accurately isn't trivial: what if someone closed the issue just before you merged the MR?
All other issue tracker I know (bugzilla, redmine, ...) don't enforce transitivity. Sometimes, blocking bugs are used to track regressions. Sometimes, blocked bugs are meta bugs, and can be closed when the major blockers are done.
@smcgivern : I wasn't trying to solve the blocking mr merge problem. Definitely I agree we should try to get the smallest version in first. So the mental model I have is that the "blocking" constraint is only considered and enforced when there is an attempt at closing an issue. So I was trying to enumerate all those possible events. Definitely I think enforcing it as an ongoing state would be too complex as a first iteration.
At least this is what I think from a simple first iteration in terms of product complexity and implementation complexity. Please let me know if it doesn't make sense technical-wise.
So with that in mind:
I assume that if issue A is closed, then issue B is closed, then issue A is reopened - issue B is not automatically reopened?
Totally. This is an edge use case. Since B is already closed, I don't consider it at all. I only consider what happens when I attempt to close B.
Similarly, if issue B is already closed when it is set as being blocked by issue A, it can be reopened, but it can't be closed if it's then reopened until issue A is closed?
Yes again! In my mental model, I only consider the constraint when closing B. Re-opening B is not part of the constraint.
Regarding merge request and the words there, we can figure out what to put in terms of text copy and what's feasible later. But I wanted to at least figure out what is feasible in this first iteration. One possibility is to totally ignore auto-closing in the constraint. That is, in my model above, I consider only the action of manually attempting to close B, and it is blocked / prevented. We can release a version to say if B is auto closed via a merge request, the blocking constraint doesn't consider it, and therefore, it can still be closed via merge request. I think ideally we wouldn't want that and we could prevent that from happening in the first iteration. Thoughts?
@victorwu I wonder if we could go the other way, and just not deal with the MR widget text, but still enforce the constraint on closing a blocked issue?
@smcgivern : Sure. I don't see the widget text as being a huge problem anyways. But what do you envision regarding the auto-closing feature in the first iteration? I.e.:
Issue A blocks Issue B.
Issue A is open.
Issue B is open.
MR C is marked with "Closes Issue B"
When MR C is merged, what should happen to Issue B?
@sarrahvesselov : We'd need some UX design for blocking issues to review just the concept, and the many places it impacts. Probably earliest we'd work on this is 9.5. I can ping you again when we are more certain we want to action on this.
If a merge or push say to close an issue and it doesn’t, what is the feedback given to the user to indicate this? I envision people contacting support “I used the issue closing pattern in my commit but the issue isn’t closed!”
Would it be a viable MVP to ship a simple blocking relationship (no auto closing)? That auto closing bit seems very complex while we could get the minimal feature shipped with very, very little work (add new relationship type).
@dblessing : What do you mean by no auto closing? Do you mean that as a first iteration the auto closing would not respect this blocking relationship? So you would only respect this relationship when you attempt to close an issue manually? (i.e. through a button click or a quick action?) Certainly I think the UI would be easier in that case.
@victorwu I used the wrong term. Instead of auto-closing I mean preventing the closing of a blocked issue. Implement the simple relationship (basically, a related issue with a different name) but don't worry whether a user can close an issue that is listed as blocked by another. We can introduce that in a future iteration since it's complex - see @smcgivern's comment at https://gitlab.com/gitlab-org/gitlab-ee/issues/2035#note_31401778
@dblessing : So do you mean we simply create a new section in an issue, called "blocking issues"? (And maybe equivalently, a mirror section called "blocked by issues"?) But the actual blocking mechanism is not implemented until a later time? Wouldn't that be too little functionality? Essentially create just a dedicated area to list a bunch of issue relationships? Which we already have, i.e. related issues.
@victorwu Correct. I don't think it's too little functionality. By default I don't think our leading competitor in issue tracking does anything here, either. They have an option called 'validating issue links'. The basic important piece is having that visual title that says 'blocking issues' - it's much more obvious than 'related issue', which could mean anything.
@dblessing : Gotcha. I think that could work. As a middle ground, what do you think of simply displaying somewhere that there's been a violation?
For example, suppose you've entered this relationship: A --> B, i.e. to implement B you really really should first implement A. Or to close B, you really should close A first. Now suppose B is closed, but A is not. Then somewhere in issue A or issue B (or probably both), there's some UI indicating you've violated this intended relationship. The UI is essentially a call to action to tell you to either fix A asap or maybe revert B.
This seems like a very useful feature, and you could simply render the violation when you load the page. (So not a lot of extra effort.) And you don't have to worry about the blocking mechanisms we've talked about above, at least for this issue.
+1 for that just having the blocked relationship type is useful.
For us this isn't primarily about blocking the closing of issues but rather about filtering out. I.e. in the normal day-to-day view where we pick up issues to work on we don't need to look at the blocked ones. We try to look quite far ahead and split things up in lots of smaller issues but you can't work on most of them since they are blocked on some issue that needs to be completed first. It's like long chains of issues describing the work. This means we have a good overview into the future but if a programmer just tries to find an issue to work on right now, half of the issues might not be relevant because they are blocked on something else. The blocked/blocking relationship would help us greatly in this area!
Also, I really don't get the EEP status of this, that seems excessive. Issue relationships are in EES, right? So why would a blocking relationship be EEP rather than EES? That's just weird.
If such a basic and all around useful feature is implemented for EEP only, that would be a massive disappointment, all it would do is to push us towards dedicated ticket management systems and NOT incentivise us to upgrade as someone might think.
Is there any chance of the development priority of this feature being upgraded? I'm really surprised this isn't already implemented to be honest. A label is not at all a substitute.
Adding comments here that it would be useful to see the blocking issue listed on the card in an issue board.
It would also be useful to see how long the block has been listed.
The ability to block an issue on another issue is extremely important in an issue tracking system, I find this to be especially the case in FOSS projects where maintainers need to send a strong signal to various collaborating parties; that a blocking issue cannot be circumvented.
Is this going to be available on gitlab.com ? or in GNOME's gitlab instance ?
Great ideas @mdelaossa. For the first one, since likely the design for blocking issues will be similar to related issues (https://gitlab.com/gitlab-org/gitlab-ee/issues/6086) we could probably have some special treatment in the milestone UI on the issue row indicating that it’s the same as the current issue. So a pretty small iteration.
Maybe this is already covered, but it should be possible to see an issue board of blocking issues where they inherit the milestone of the issue that blocks them. Also, an email sent for the blocking issue that the milestone changed should result in an email sent for the blocked issue that a milestone changed.
I was looking to add an issue for this feature over in the community edition repository and was pointed here.
Many issue trackers have this type of relationship as a basic feature (Bugzilla, Taiga come to mind); could we reconsider this feature's placement and make it available in all editions?
@gitlab-org/coaches I believe that the general rule of thumb is that when accepting merge requests for a feature it can be considered for CE inclusion; right?
@jonas1 : Provided GitLab team members haven't already started working on a feature, you are free to submit a merge request to whatever license you'd prefer. See https://about.gitlab.com/company/stewardship/#contributing-a-not-yet-existing-feature for additional details. In this particular case, we indeed have not started work on it. Are you interested in contributing?
Oh, I'd love to use those blocking issues! We have a very complex set of dependencies between issues, and often we cannot even start working on one if another is not completed and shipped.
This will help keeping track of the relationships.
@bikebilly Your best bet at this point is to write a bot using the webhook system and the API to manage dependencies. That's what we do. I have a Python bot that keeps track of dependencies in a special section of the issue description. It uses labels as well to indicate what is blocked/required. It can't, of course, enforce that no work starts (nor can any other system), but it at least keeps track of the details so you know what's going on.
I work for a foundation in Chile (the Fundación Ciudadanía Inteligente) and we are users of the Community Edition. I'm looking for ways to improve our workflows, and one of them would be this! Since we have very little resources, a tool to decide where to allocate them more efficiently (such as towards the critical path of Issues for a project) would be really great :)
I might be able to help beta test this. @gweaver ping me if you need a hand on that!
@mjwood What do you think about consolidating the discussion around issue dependency management here. Would you like to lead the validation process on this? I'm happy to collaborate on it together, but feel like it may have favor the ~"group::certify" roadmap a bit more. 😄
Re-adding my comment here since the original epic got closed:
@gweaver I find the blocking issue feature really powerful for our own planning. From an engineering perspective, we can have some constraints in the order of execution of some tasks and it's hard to see this with current tooling.
The only way to define this "is blocking"/"is blocked by" relationship is by putting comments or mentioning it in the description (on top of using related issues).
By being able to explicitly flag an issue as depending on another one, we could make prioritization and planning way more efficient. E.g. this could allow us to provide nice helpers:
adding a (low) warning to an issue if it has a blocking issue that is planned in the same iteration. In such case, it can be totally fine but if for any reason the blocking issue got delayed or can't be done in the iteration, the blocked issue won't be delivered either. That's worth mentioning. This also helps to prioritize the blocking issue to start at the beginning of the iteration.
adding a (high) warning to an issue if it has a blocking issue that is not planned yet (backlog) or planned for a later iteration. In such a case, it is unlikely that the issue could be delivered so it should be clearly stated so planning can be adjusted before the iteration starts.
Having such warnings visible in the issue board or issues list could be a great time saver for PM and EMs.
NB: I was relying a lot on this relationship when using JIRA.
@mjwood I think this is a simple MVC. I definitely would not consider the historical stuff or worry about enforcing closing of issues in any sort of specific order. If an issue is closed that is blocked by another issue, it's possible the team decided to just not do it.
From a UX standpoint, I'd also like to see the related issues sorted by:
Blocking
Blocked By
Related
and it'd be nice if we could just use icons to denote the three possible relationships.
From an implementation standpoint:
Are related issues in the public API at this point?
Should we keep the dependencies as a top level attribute on an issue so we don't have to traverse through related issues to get the dependencies when we are mapping issues to one another in a more visual form?
From a UX standpoint, I'd also like to see the related issues sorted by:
Blocking
Blocked By
Related
^Agree with this.
Are related issues in the public API at this point?
Probably need someone from Engineering to help us answer that. @johnhope any idea?
Should we keep the dependencies as a top level attribute on an issue so we don't have to traverse through related issues to get the dependencies when we are mapping issues to one another in a more visual form?
@gweaver - Thanks for the feedback on this! I agree - from a program perspective, the goal is to be able to identify issues blocked by other issues, and those which are blockers. I'll clarify the problem statement.
Ideally, I'd like some form of visual representation of these two situations.
@mjwood@uhlexsis This is probably oversimplifying but wanted to post these ideas for the sake of time and to get the conversation on design going. I'm also sure I'm breaking some of our design system standards so that too will need to be addressed before moving it to UX ready. I see the conversation above about auto-closing but was thinking for the boring solution that perhaps we could just provide a visual in the primary related list with a blocker icon and then a separate Blocked tab with filtering options for viewing Blocking, Blocked By. Thoughts?
@hollyreynolds I think we should separate the Blocks and Blocked by into their own sections, and I'm not sure if we should put them behind a tab. We want dependencies front and center so users can quickly see what is blocking what. My $.02.
@kokeefe I agree. I think there are better ways to surface it and more that we need understand surrounding it so this is one I'd like to get a quick solution in place for but then create another issue to dive a little deeper into ensuring we're addressing the right problem and truly solving it. In this case, items either causing or affected by a block show in two locations (possibly three if we broke them into multiple tabs): the primary related issues list (which I renamed here to "All Related Issues" and that would likely need to be a separate conversation), then also the specific tab for Blocked Issues.
Happy to break the blocked issues into two separate tabs if that makes more sense, but is there value in seeing them all in one location (blocked and blocking)?
Other questions I'd like to consider (though we may not have time to fully investigate currently) are:
At what point in a process (and what process) is understanding blocked and blocking items useful?
Who typically needs to understand this information and why?
How are they currently getting insight into blocked issues? And once they have insight, what are they doing with that information to address the problem?
What other challenges surrounding blocked and blocking are they currently experiencing?
What places would it make sense to the users to see this type of information?
What level of priority is surfacing this information to users?
@mjwood can chime in here too, but I'm not a fan of putting these behind tabs.
@hollyreynolds I was thinking more along the lines of this:
At what point in a process (and what process) is understanding blocked and blocking items useful?
Understanding dependencies is critical through the entire dev cycle. Planning, scheduling, development, and release all rely on understanding blocking work.
Who typically needs to understand this information and why?
The Product Manager, Dev Team leader, Eng Manager, and the developers doing the work all need this info.
How are they currently getting insight into blocked issues? And once they have insight, what are they doing with that information to address the problem?
Currently, they add it as a related item, and add something to the description, or within the discussion that states the dependency. Very manual, not easily trackable.
What other challenges surrounding blocked and blocking are they currently experiencing?
If you can't map dependencies, it is hard to plan the proper sequence of work. User's end up writing bigger issues, with higher weights, just to keep the work in a single place so nothing is missed.
The only way to know if an issue with a blocker is ready to work on, is by investigating related issues, re-reading the description or the discussion which means they are context switching and opening multiple issues and cycling back to the original item.
What places would it make sense to the users to see this type of information?
On the issue and epic views
On the Roadmap
Some future view that shows a Critical Dependency Path (a chain of dependent work that blocks a projects completion)
What level of priority is surfacing this information to users?
Very High
How are others solving this problem?
Competitors like JIRA surface this info prominently and build features around it to help users plan work and mitigate blocking issues. This is table stakes functionality.
Most other software solving this problem displays this information very prominently. I suggest we do the same.
I will note that I think there are three buckets than an issue can fall into:
Related Issues - issues that are related, but have no direct relationship. Blocking / blocked issues should not show up here.
Blocked By - Issues that are blocking the current issue.
Blocking - Issues that this issue is blocking.
I like Keanon's sketch, but I would suggest putting them in the following order:
Blocked By
Blocking
Related Issues
People want to first know what is blocking the current issue they're reviewing. They next want to assess how many issues the current issue is blocking. Thirdly, they want to see related issues to gain context.
@hollyreynolds@mjwood Maybe we could just tweak the control when adding issues/epics and basically add a dropdown allow the user to select the link type. Then the issue gets added to the "bucket" below that the user has specified. Here are my rough thoughts:
Things I wonder here:
What do we call this list. Linked issues? Still related? Something else?
What is the purpose of the overall counts now? Does a user need to know the cumulative weight and count of all "linked (blocked, blocking, related)" issues?
Would there be be purpose to seeing counts for each section? Does a user need to know the cumulative weight and count of all linked "blocked" issue for example?
Does a user need to see both of the above?
How does this fit with our tree vision? I think we should get @annabeldunstone involved here since she did a lot of tree work.
There is also a new vision for creating/adding issues and epics, just to be cognizant of that. Maybe Annabel can link some of those because she has done work there too.
What do we call this list. Linked issues? Still related? Something else?
Let's keep in mind, that we should support Epics as blocks/blocked by items, so the name needs to reflect that.
What is the purpose of the overall counts now? Does a user need to know the cumulative weight and count of all "linked (blocked, blocking, related)" issues?
The count is important. Knowing an issue is blocked by multiple other items is valuable info. I think weight would be a valuable piece of info as well, since they'd have to go look that up to make a decision anyway.
Eventually I think we should reflect the number of blocked/blocking items all the way up the chain. For example:
Issue A blocks Issue B which blocks Issue C.
Let's say Issue D is blocked by C... should we show 1 Blocker? Or 3 Blockers
I say 3, but that can be future addition.
@mjwood thoughts?
Would there be be purpose to seeing counts for each section? Does a user need to know the cumulative weight and count of all linked "blocked" issue for example?
I say yes.
Does a user need to see both of the above?
Not sure I understand the question @uhlexsis, both of what?
How does this fit with our tree vision? I think we should get @annabeldunstone involved here.
Well, the Tree represent all the work(both sub-epics and issues) in an Epic.
Blocks/Blocked can be issues and epics from somewhere else... not necessarily from the same Parent Epic. So dependent work won't always show in the Tree.
There is also a new vision for creating/adding issues and epics, just to be cognizant of that. Maybe Annabel can link some of those because she has done work there.
Agreed, good call.
Let's just remember there are 2 separate problems here... linking an issue or sub-epic to an Epic because they are int he same collection of work.... and linking an issue or epic because it is a blocker/blocked by.
Eventually I think we should reflect the number of blocked/blocking items all the way up the chain. For example:
Issue A blocks Issue B which blocks Issue C. Let's say Issue D is blocked by C... should we show 1 Blocker? Or 3 Blockers
I would agree - we should be counting all blocked issues down the chain. I'm happy with the MVC not including this, but I think it would be a great follow-on update.
It could get confusing... perhaps a Blocks 1 (and 2 more indirectly) or some logical separation like that. Should be for blocked by as well. Blocked by 3 (and 10 more indirectly)
@kokeefe I meant both as in do we think it would be useful to have:
An overall count next to the header of Related issues (as it is now) or Linked issues (as it is called in that sketch), where we show the cumulative weight and issue count of all issues tied to the current one (blocked, ones it is blocking, related, etc).
AS WELL AS
Counts next to each section (ie: Blocked by) showing cumulative issue count and weight of that section.
I would agree - we should be counting all blocked issues down the chain. I'm happy with the MVC not including this, but I think it would be a great follow-on update.
@mjwood
That makes sense- showing the exact hierarchy here could be the next iteration. 👍
@hollyreynolds is working on mocking up that sketch so we can discuss it further. I was looking at #5419 (closed) when thinking of the linking a dependency of an existing issue vs creating a new one FYI Holly. I feel like there was a similar issue and design for creating these from an issue instead of an epic, but I can't find it. Do you know @annabeldunstone ? I would think users would want to quickly create issues within this widget, similar to how they will be able to in #5419 (closed)
I feel like there was a similar issue and design for creating these from an issue instead of an epic, but I can't find it. Do you know @annabeldunstone ?
@uhlexsis I'm not sure; I can't remember it off the top of my head 😬
One question- we're talking about stacking widgets rather than using tabs to separate them. Adding a vertical list of widget upon widget before you get to the issue discussion reminds me a lot of the MR widget. It started out a lot smaller years ago and look at the size of it now! We keep adding stuff and it's getting longer and longer.
Does anyone have any thoughts on putting all three of these widgets in a tab? Something like this-
If that's too hidden (which I would definitely understand), could the widget be collapsible?
@mjwood@gweaver ok so... do we really think this is Ultimate functionality?
I see it as pretty tablestakes, and would advocate for Starter (Since it would only be Issue to Issue dependency at the moment)
@stkerr Agreed.
Now, there are features we can build on top of this over time that target Directors and strategic business users (critical path mapping, assigning a risk flag to projects with long dependency chains, recommended sequencing, etc) that can live at Ultimate, but the basic functionality is needed at Starter.
@kokeefe - I think it's currently targeted to Premium, but I'm not sure the history behind that. I too would advocate for Starter because I feel that it's a basic feature for any team to collaborate.
@jzidell Gotcha, that is helpful.
In that case I think marking A as a blocker of B makes sense, since A needs to be completed for B to be completed, regardless if it is work or a merge that's needed.
You do bring up a good point about work being able to be parallelized, while still being a dependency. @mjwood we should think on this use case for future MVC work.
Once we get this in place and we can surface dependencies on the roadmap, the sequencing problmes can be tackled.
@kokeefe - I agree - I'd like to explore this more once we have the initial work completed. In my eyes, a blocking issue is more about when an issue can be completed / closed and less about when it can be started, but until we can see dependencies on a roadmap, I'm uncertain how that will work in reality.
@mjwood@kokeefe I created some mockups based on Alexis's wires above. I am happy to go with exposing everything in a single view rather than tabs, but do think we may need to explore possibilities surrounding hiding some of those in the event the list gets long. Thanks for answering my questions above as well!
I left the "add" control at the top in my sketch intentionally. I think it makes sense to leave that control in one place where a user expects to find it instead of scrolling through a (potentially) long list of issues to find blocking for example and add from there.
I had Jira in mind when thinking of this, for example:
I think having one place where one can expect to add makes it more usable and flexible for if we add more dependency types. 🤔
@uhlexsis Ok, fair enough. That makes sense.
The current buttons are create vs Link, in a section called "Linked Issues".
(Again, we need to account for Epics as dependencies too)
What is the value in re-ordering linked issues within an issue view? If we expose this information on an Issue Board and/or within an Epic, it seems like that is where "prioritization" would likely take place.
There is already a lot of wonkiness in D&D because it changes relative order globally and as of today, there is no SSoT location for defining the relative priority of one issue to another so folks inadvertently change the priority of an issue that another team member may have just updated.
@gweaver I often re-order items within an epic to move the closed issues to the bottom of the list. Something similar here might be useful, particularly if there are a lot of items.
Could also go in a separate issue as a future enhancement. Just want to make sure we're not using styling that indicates drag-and-drop functionality (box-shadow seen in issue boards and epic tree) if the items cannot be moved.
Essentially the user lists the MRs that must be merged before the one they are currently editing. When viewing the MR, we list them in the MR widget under “Depends on X merge requests being merged”. So we only allow defining “blocked by” but not “blocks X”.
It would be great if we could keep in sync about these developments as the user's expectations may carry from issues to MRs and vice-versa — I'm not saying that this feature should behave the same, just that we should know what's happening in both Plan and Create.
@fatihacet and I discussed this earlier. We should at minimum be able to use some of the frontend code here, but it would be nice if we did reuse some of the same user behaviors.
@donaldcook Agreed, where we can.
Elements of the dependency tracking we are implementing here are focused on different users than MRs. As a PM or EM planning my teams work, I care abut the functional chunks of effort (Epics/Issues) that I need to map and sequence, not the individual MRs.
Related, absolutely, but focused at different parts of the dev process.
@pedroms Thanks for bringing that to our attention! Are there any specific areas you'd recommend we consider to reuse here? I'm struggling to see the similarities in the UI so perhaps it's more of a functional similarity in the approach? Perhaps there's something I'm missing 🤔
@pedroms devil's advocate here: if blocking issues are a special case of related issues, wouldn't it have made more sense to reuse elements from related issues for MR dependencies? It seems odd to me to say that MR dependencies are the precedent when we've had related issues since GitLab 9.4 in 2017 😃
I think what @kokeefe and I are most interested in is the idea of planning blocks of effort. In my mind, issues are discrete pieces of effort, which make up an epic (larger block of effort) which can in turn roll up to additional epics. MRs are, in my world, the actual changes which implement the block of effort.
With this in mind, I'd like to see the interface for blocking issues stay similar to related issues as much as possible, though I'm sure it may be helpful to review the blocking MR solution!
We should have a cohesive user experience across Issues and MRs. If we uncover a better way to present blocking issues as part of this work, we should also contribute those benefits to MRs where appropriate. T
Elements of the dependency tracking we are implementing here are focused on different users than MRs. As a PM or EM planning my teams work, I care abut the functional chunks of effort (Epics/Issues) that I need to map and sequence, not the individual MRs.
Yes and no. The same concept hold trues. One thing has to get done before another thing -- whether that is an issue or an MR.
With this in mind, I'd like to see the interface for blocking issues stay similar to related issues as much as possible
Yes...I think the main differences will manifest not on the issue itself but on how we present these relationships on issue boards, epics, and roadmaps.
I didn't mean to imply that this feature should look and behave the same as MR dependencies, as the goals and personas are different. I just wanted to share the approach we took with MRs, to see if there was something to learn from that (positives and negatives). In the future, I believe we should balance the consistency between issues and MRs, and have good reasons for making them different.
@hollyreynolds Good question, I don’t know to be honest. The big difference right now is that issues don’t have a dedicated edit view/form, it’s all inline editing. Merge requests have a dedicated edit view/form, where users specify the blocking MRs.
@smcgivern good points (and I appreciate when someone plays the devil's advocate 🙂). With MR dependencies we are actually using the same kind of input for listing related issues. The difference in experience, as I hinted above, has to do with the inline editing (issues) vs form editing (MRs) — and also the existence and purpose of the MR widget.
Thanks for clarifying @pedroms! Per our discussion in Slack, I agree that one of the big differences in how we approach adding blockers in MRs is that it has a dedicated Edit view whereas Issues are inline. Do we know why that is? Was an intentional decision made surrounding the design of one vs the other?
And would this possible approach allow us to re-use some components? I also switched the 3 options from a dropdown to a radio list as it just felt too few to hide behind a dropdown. Not sure if we would be looking to expand the number of options in the future or if there are other patterns to consider but wanted to propose it anyway.
@hollyreynolds - I like the radio buttons. I agree, forcing a user to go to a drop down and hide the three options seems to make them harder to discover.
@hollyreynolds good call. I'm a pretty big fan of GoodUI.org. This is Item 14 on their list and they have a ton of data to back this pattern up. It might be worth exploring as a fairly cheap (relatively speaking) data source for the UX team. https://goodui.org/patterns/14/
Ya this makes sense to me @hollyreynolds !! I only had the dropdown thinking we would have more dependency types. Looks like we currently will only have 3, so this is great! 👏 If we add more- we will worry about it then.
Removing friction in switching dependency types surfaces something I hadn't thought too far into. This makes sense when a user is adding one issue at a time, but what if they are intending to add a few issues with different dependency types at once? So let's say a user:
Clicks blocking
Types an issue, it tokenizes
Clicks blocked by
Types an issue, it tokenizes
User clicks 'add'
I wonder if a user assumes that they have applied 1 blocked and 1 blocking issue or 2 blocking issues🤔 If we truly wanted to allow users to add all types at once, we'd probably want to explore tabs with counts or something here- which seems overcomplicated for mvc. Honestly- I am assuming what we have here is clear enough! 🚀 Could lend to some quick usability testing in the future though.
Maybe just some form tweaks could help with this as well. We could add some contextual help text to that "Issue" input to provide some education on the action? Almost like a stepper, something along the lines of (B below):
If user clicks 'Blocked by" under "Add dependency/link type" the input below reads "Issue(s) that are blockers to the current issue"
If user clicks 'Blocking" under "Add dependency/link type" the input below reads "Issue(s) that are being blocked by the current issue"
If user clicks 'Related" under "Add dependency/link type" the input below reads 'Issue(s) that are related to the current issue"
Or we could lean into the conversational aspect (A below). Or any mix n match comboing we want to do.
Either way, we probably want to be consistent with what a user select in the radio and what displays in the list. What do you think? 🤔 Just some more ideas!
@uhlexsis Love the idea of providing additional context like you have in example B! Should we also add clarity in the List view? Perhaps the ? with a tooltip?
Sorry for not getting to this asap @hollyreynolds but I think a tooltip could make sense! As long as it isn't cluttering or causing friction I like to err on the side of over-education (if there could ever be such a thing!!).
To sum up what we talked about Friday @hollyreynolds so we can keep track of this ✨
I think these are the lingering questions I have are:
What terminology should we use (ie: is blocking vs Blocking , Related vs Relates) and how to make that consistent when adding and also in the list
Is adding that help text under the issue input enough of an indication that the user is adding only one link "type" (I assume so, but we can do quick usability testing internally as we chatted about)
Does a user need a overall count of linked issues as well as the count of each link type? @mjwood says maybe not #2035 (comment 233584301)
How can we keep this experience consistent across both the issue and epic view?
Epic
Issue
How can we integrate this gracefully into the epic tree (maybe @annabeldunstone can support as we implement this there)
How can we integrate this gracefully into the epic tree
@uhlexsis@hollyreynolds I don't think the epic add feature is the most user friendly, so I think we should move forward with whichever is best for issues and revisit epics later (maybe we can utilize the radio buttons that are being used here; you choose Add epic and then use a radio button to select existing or new 🤷). That being said, to make things align a little better, what if we updated the issue + button to read Add an issue and moved it to the right side of the widget?
I think so. Being able to quickly see and say "Whoa, this issue blocks 8 other items" would be extremely helpful.
@kokeefe, @uhlexsis - Completely agree. Being able to see number of blocked issues is key. I think what I was trying to say earlier is that I open to not seeing the number of related issues because I don't see as much value there. For blocked / blocking, I think there is a lot of value.
It isn't necessary in my opinion @kokeefe ! I was proposing we just make the labeling as clear as possible so that users understand that is not the case. :)
@mjwood Which is these dependency types would users be choosing most often? This helps us think of what is default, or how it impacts the design if there is no clear default.
@annabeldunstone@mjwood@uhlexsis I think we are leaning toward the second example above but I created a simple prototype just to get a couple of key questions answered and scheduled a few testing sessions for tomorrow. Hopefully that will help us to finalize the approach and move this one on ahead!
@rdickenson Would love your thoughts on the verbiage we are using for this. There are two designs being proposed (and we are conducting internal A/B testing on them right now using prototypes). We want the following to be clear:
That the issues being pasted in are either blocking the current issue, blocked by the current issue, or related to the current issue.
That they can only add issues to one type (blocking, blocked, related) at a time. They can add multiple issues to that type (multiple that would be considered blocking, for example), but must hit Add before being able to add some to a different type.
Not everyone was clear on what "blocked by" and "is blocking" meant, even with the message displayed below the field. They seemed to explain it properly when I asked what they thought it meant, but two expressed that initially they didn't know prior to my asking
Half of the users correctly guessed that they would need to click "Add" before being able to create an association with a new linked type. The other half expected that they could select another radio button, paste in another URL and it would somehow correctly associate some of the items with related (for example) and some of the items with blocked by or blocking with one submission
Some wanted the ability to easily select Related AND Blocking OR Blocked By in one step
Everyone mentioned that they were curious how the list view would work if there were several items in the Blocking and Blocked By sections (tabs perhaps?)
One person said they saw Blockers as more of an edge case and that by default they would expect to see Related selected as that's what they'd be doing the most in terms of Linked associations.
I'm working on a new design and would love to collaborate with Alexis when she's back from PTO on Wednesday once I have that ready so we can hopefully wrap this one up:)
@hollyreynolds you are a rock start!
Thanks for running with this and thanks to all who provided feedback.
Some wanted the ability to easily select Related AND Blocking OR Blocked By in one step
So, Blocking or is Blocked By is a relationship between 2 items... marking something as both would be redundant in my opinion.
Everyone mentioned that they were curious how the list view would work if there were several items in the Blocking and Blocked By sections (tabs perhaps?)
I would caution against tabs personally, as it obfuscates the relationship. In reality, we are simply breaking up the existing Related To list into 3 categories to better define and visualize the relationships between issues.
One person said they saw Blockers as more of an edge case and that by default they would expect to see Related selected as that's what they'd be doing the most in terms of Linked associations
Interesting, I wonder if thats simply because that's the only option we have had in the past?
@hollyreynolds Consider that "blocks" and "blocked by" are subsets of related. Related represents any kind of relation, which until now existed only in people's minds. Now we're explicitly highlighting two subsets (there likely are more such subsets). Would it make sense for "related" to be the default, as it is now, and "blocks" or "blocked by" can be optionally chosen if the user so desires?
Another way to put it is, "related" are all issues that don't fall into the "blocks" or "blocked by" buckets.
I have had this same struggle mentally while following this thread. I mean on one hand it makes sense that Blocked and Blocked By are subsets of what we are currently putting in the related "bucket". But if you came fresh to GitLab after these other concepts existed then I feel the mental definition of "related" is just that "these are sort of about similarish things" . And they aren't necessarily subsets.
I'm not really disagreeing or agreeing with you @jzidell, just saying it's a hard one for me to land solidly on one or the other. And it's also equally hard for me to decide what the "most likely" scenario is given my muscle memory for saying/thinking about "related" as the only option.
@hollyreynolds - Thanks for reaching out on this issue. It's interesting enhancement.
For the verbiage to be used in these dialogs, it's not easy to think of something definitive. As @adam.dehnel mentioned, Related seems to cover the three options discussed in this issue. However, the word Related is already in use, and has an established meaning in GitLab. To change this meaning within the product risks confusing existing users. To help ease potential confusion, we could add tooltips to each option.
Before getting to the wording, do you think it would be easier for users if a dropdown was used to list available link options, instead of radio buttons? The advantage of using radio buttons is that all available options are listed, so it's more easily discoverable by someone new to the feature.
To ensure users click [ Add ] for each option, I think we could disable the other 2 radio buttons until either [ Add ] or [ Cancel ] was selected.
In the design, you have the field label Add issue(s), which makes it clear that one or more issues can be listed.
Finally, to the verbiage. :) I would prefer not to have block in two of the three options, but that's a personal preference than anything else. An alternative to Blocked by would be Depends on, but I'm sure that would be an improvement.
For the Add issue(s) input field, I suggest minor changes to the accompanying text:
Blocked by
These issues block progress of the current issue.
Blocking
The current issue is blocking progress of these issues.
@kokeefe Thanks! Just to be clear, they wanted the ability (in some cases) to mark something as related AND blocking OR related AND blocked by. So here are the scenarios I gathered they'd ideally want:
is related to
is related to AND blocking
is related to AND blocked by
is blocked by (not related)
is blocking (not related)
Now I wonder though if the second and third are redundant? If there is a blocker, isn't that considered a relationship? However, if they eliminate the block, does it remove the relationship? To Russell's point above, there is already a concept in place for existing users surrounding Related and what that means. Would this break that idea?
But I'm inclined to agree on the tabs. Working on some design proposals for this now. And not sure about the edge case idea surrounding blockers - possibly? I wonder if it depends on the role too? This person was a dev manager. Would a PM have a different experience?
@jzidell I think it would make sense to default to Related as well. That seems to be the option most commonly used and currently the only option.
@rdickenson Thanks!! I am wondering the same thing about the relationship being applicable in any case. But I'm a little confused regarding the Add, Cancel and Depends On suggestions. Would you mind expanding on those a bit?
@hollyreynolds - To answer your question about my Add and Cancel suggestions, I was referring to an earlier thread in which you wrote:
We want the following to be clear:
That they can only add issues to one type (blocking, blocked, related) at a time. They can add multiple issues to that type (multiple that would be considered blocking, for example), but must hit Add before being able to add some to a different type.
Note that I'm probably stepping beyond (technical writing) role, but I'll explain briefly what I meant.
When a user wants to add a relationship between this issue and another, they select the appropriate radio button, then enter the issue ID(s) in the input box. Once they have entered at least 1 issue ID, the other 2 radio buttons are disabled. At that point they can only click [Add] or [Cancel].
To explain the Depends on suggestion, I meant it could be a replacement for the phrase Blocked by.
The top 3 bullets are the use cases we should support for this MVC.
is related to AND blocking
is related to AND blocked by
If the issue BLOCKS an issue, that is the relation. Assigning both complicates the purpose of this issue, which is to enable dependency mapping between artifacts.
is blocked by (not related)
is blocking (not related)
I'd argue these scenarios do not exist^
If they block or are blocked by an issue, that is the relation.
there is already a concept in place for existing users surrounding Related and what that means. Would this break that idea?
This expands how Related works. If the user's want to continue to leverage it as they have in the past, nothing prevents that. We are just adding additional clarity on the types of relation to empower teams to map, track, and understand dependencies in their work.
not sure about the edge case idea surrounding blockers - possibly? I wonder if it depends on the role too? This person was a dev manager. Would a PM have a different experience?
I'd argue this isn't an edge case, but a primary set of functionality we do not support, that our competitors in the market do. There is value for individual devs, to dev managers, to PMs.
@kokeefe@uhlexsis OK how about this? Per our conversations earlier today, we're moving forward with the radio button design with the intention on learning a little more about the user needs surrounding this feature as we go.
Dangit, sorry @hollyreynolds , moving from slack to here.
For MVC, I think tooltips should be fine. I'd love to make that help text more contextual though as future scope.
Could you put the add and cancel buttons within the "This current issue" card (the white box)? I think that would better correlate the act of adding with the input above it, especially since there is no longer a line break between the adding widget and the list. WDYT?
I think it would be helpful to have the language consistent across both the list and the adding experience (ie if we use Is related, should it perhaps be Is related in the list as well?).
Having the ordering in the adding experience be consistent with the list would be helpful as well I am assuming (ie if "related" is first in the fields, having it first in the list).
There are some tiny design things going on here (ie the token control for clear/remove being disconnected) but honestly- I think this gets the point across just fine. If anything this can lead to a good discussion next sync about when and when we need pixel perfect designs vs just quickly iterating to nail the experience and working more closely with FE.
@hollyreynolds This looks great! To nitpick, should the label of the issue field be Issue(s) to inform the user that they can choose one or more issues?
@mjwood@hollyreynolds: when adding a new related issue, "blocking" will be default relation (based on the screenshot in issue description). But to backfill/migrate existing related issues, I think we should set related to, right?
@jprovaznik It's my understanding that an issue should not be both Is related and blocking at the same time per the discussion here - #2035 (comment 240963716)
@kokeefe - should we clarify in the description that the three concepts, blocking, blocked by and related to should be mutually exclusive? I believe that is our intent since both blocking and blocked by are subsets of related to.
@jprovaznik ah.
So for issues that already are marked as related we should maintain that. We shouldn't retroactively change any issue relationship to blocking or blocked by.
I believe we agreed that related should be the default... @mjwood can confirm.
@jprovaznik@mjwood TL;DR - yes, please put Related first in the radio button list. The thinking here was that Blocked would be first in the issues list as we believe that will be more important to see than the Related. We switched it to the first radio option to be consistent with that concept.
That being said, I do prefer to have it first since it is the default selection. However, I would still prefer to see Blocked first in the list view. It will create an inconsistency in the ordering of the two areas but I think it will be OK in this case because I believe it makes more sense for the default selection to be first in the one, and Blocked to be first in the other.
@hollyreynolds@uhlexsis@mjwood This may be a bit late to add, but here is some feedback on the proposed approach. It feels like it adds unnecessary clicks vs. just having an "add" button inline with each click.
Via the proposed approach
Click + to expose interface to add link. Interface animates into container, pushing all list items down (which will feel weird).
Click related to radio input
Click into the input
Search or copy/paste related issue
Click Add (or maybe enter)
Add interface animates out, sliding everything up (which will feel weird)
Alternative approaches
Click + next to the related issues header. Animate in one row and automatically place cursor within input field.
Search or copy/paste related issue
Hit enter to save, no weird slide out animation of a large form component.
@gweaver Chatted with Mark today and we are going to move forward with the existing design for now for time's sake, but agreed it is worth revisiting ways to improve the experience in future iterations. I do like the idea of inserting a new row and simplifying that flow a bit rather than having the extra click or two.
It seems that this is unlikely to make it into %12.6. If it is still intended for 12.6, don't forget to add some docs WITH this MR please. Even if it's the bare minimum, get it in, but don't let the doc review block the MR if time is running out.
@rdickenson Thanks for reminder. Backend part was merged yesterday, it's behind feature flag (disabled by default), I'm not sure when frontend will be merged but I see @cngo has already MR for it - !21415 (diffs). We typically add documentation when the feature flag is removed (feature is enabled by default), but I suppose we could prepare documentation MR also independently meantime (with a note that this feature is still disabled by default).
I'm not sure if it gets released (enabled by default) but if it does it will be very tight - supposing that this will be deployed to production on Monday, we could still remove the flag before the release deadline.
@cngo - Is there any progress update on the docs for this feature? @fguibert has added UI feature which indicates when an issue in an issues board is blocked by another issue. However, users of GitLab.com don't have any documentation to refer to in creating these relationships.
@rdickenson Yes there is an approved MR containing documentation for this feature here: !21737 (merged). It has not been merged yet since the feature is still disabled behind a feature flag for users (however, the feature flag was turned on for this project gitlab-org/gitlab).
I have another MR to remove the frontend feature flag for this issue here: !24460 (merged). It is close to being merged, and I will get the documentation merged at the same time so the feature is released with relevant documentation.
@cngo@jprovaznik@mjwood How are grandfather'ed linked issues handled vis-a-vis changing from related to (default) to blocks or blocked by? IOW, existing linked issues are of all varieties. What's the process for changing to the correct link type?
@jzidell - I believe the idea was for issues that are currently related to, they would stay that way. We're not planning on getting rid of that category.
I meant something different. Another way to say it is, is there a way to change a link type? If a link was established as related to, can it be changed to blocks or blocked by?
I've have to consult with @jprovaznik and @cngo for a final answer, but I believe in this iteration you would have to delete the related to link and create a new blocks or blocked by link.
@jzidell thanks for raising this - as @mjwood said in the first iteration there is no way to change type of relation for existing links (IOW you have to delete and re-add). I think it makes a lot of sense to allow change link type in a follow-up issue 👍
@paebbels unfortunately I'm afraid this will slip 12.6 deadline, but I think we should have it enabled quite soon on gitlab.com once !21415 (merged) is merged.