Add tooltip to improve clarity of "detached" label/state in the merge request pipeline

added UX devopsverify typefeature + 1 deleted label

added documentation label

added 1 deleted label

changed title from Improve clarity of "detached" state to Improve clarity of "detached" label/state

changed the description

changed milestone to %12.1

cc @dimitrieh @rverissimo

removed 1 deleted label

cc @vkarnes

changed title from Improve clarity of "detached" label/state to Improve clarity of "detached" label/state, merge request pipelines feature

Some feedback on the clarity of the broader feature:

We don't note anywhere in the GitLab UI that if target has moved since the pipeline started, the MR will fail. This is a significant detail that we should display in the UI, until we have ways to work around this. (Merge Trains)
The documentation link in the ?, points to the wrong place. It points here: https://gitlab.com/help/ci/merge_request_pipelines/index.md#pipelines-for-merge-requests. I think it should point here: https://gitlab.com/help/ci/merge_request_pipelines/index.md#pipelines-for-merged-results-premium
In our docs, the fact that merges will fail is only noted way down as the third bullet in this section: https://gitlab.com/help/ci/merge_request_pipelines/index.md#pipelines-for-merged-results-limitations. It's sort of the fine print, and could easily be missed.

I think this can lead to users enabling this feature without truly knowing all that it does and it's limitations. For example I was talking to a large customer yesterday about a different topic, and they noted that they had broke all MR's recently and had to figure out why, ultimately tracing it back to this checkbox. They then had to go and tell all of their users not to enable this checkbox, as it is likely to break their projects.

Indeed, users are confused with this behavior. I recently jumped in https://gitlab.com/gitlab-org/gitlab-ee/issues/11401 and documented https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28050.

We actually remove this merge-block in %12.0 as we discussed in https://gitlab.com/gitlab-org/gitlab-ee/issues/9186#note_167093786 (i.e. in favor of merge train). This will let users merge immediately if something urgent patch came up.

We actually remove this merge-block in %12.0 as we discussed in https://gitlab.com/gitlab-org/gitlab-ee/issues/9186#note_167093786 (i.e. in favor of merge train). This will let users merge immediately if something urgent patch came up.

@dosuken123 are Merge Trains still planned to be Opt-In only, or would they default to on if you select Pipelines for Merged Results?

Note, I broke out my documentation comments into a separate issue as it is hopefully more actionable and less effort than the broader detached label: https://gitlab.com/gitlab-org/gitlab-ce/issues/62703

are Merge Trains still planned to be Opt-In only, or would they default to on if you select Pipelines for Merged Results?

Opt-In only. So maybe we can disable the merge-block when Merge Train is enabled.

Personally, I'd love to see us having only one project-level option "Merge pipelines will try to validate the post-merge result prior to merging" because Merge Train is just one of the auto merge strategies as well as MWPS is, thus users will still choose a merge strategy from Merge Train, MWPS and Immediate Merge.

@joshlambert https://gitlab.com/gitlab-org/gitlab-ee/issues/11222 (12.1) is where we change the default behavior you were previously asking about.

added [deprecated] Accepting merge requests label

mentioned in issue #62334 (closed)

added Category:Continuous Integration label

@dimitrieh you worked on the UX for this issue, right? Can you provide us with some guidance? Thanks

added direction label

@dimitrieh will you be able to look at this item? We're at risk including in %12.1 if there's no guidance.

changed milestone to %12.2

@rverissimo it doesn't seem Dimitrie is responding in this item any longer, so lets not rely on anyone from outside the team for %12.2.

Noted. Thanks for updating the milestone

@jlenny @rverissimo it seems this one slipped by due to notification overload. A slack pm is always possible if you need something asap.

The background I can provide is that we utilized the tag UI in order to be able to distinguish between attached and detached merge request pipelines.

It seems this is non-ideal, though the problem statement in the issue is not clear about why this is the case. Imo starting with finding out why that is the case should be the first action item.

Thanks @dimitrieh!

marked this issue as related to #62703 (moved)

changed the description

added devopsrelease [DEPRECATED] label and removed devopsverify label

mentioned in issue #63312 (closed)

mentioned in issue #63625 (closed)

@jlenny Can you expand a little bit on the measure from user community that drive this request? @rverissimo wants to make sure we understand the root problem and that we are solving for that.

@cstasik the issue is that what the detached label means, even after reading the documentation, is not clear because the documentation has strange syntax and/or incorrect information. Alerts in the app itself are also hard to understand. There's more similar feedback at https://gitlab.com/gitlab-org/gitlab-ce/issues/62703.

My recommendation would be, as someone with a new perspective yourself, to go read the documentation for detached and see if it makes any sense to you.

Tentatively assigning @nfriend for %12.2 frontend efforts.

added frontend label

assigned to @nfriend

@rverissimo @mnichols1 #62703 (moved) should be achievable for %12.2 but for this issue and the scope

Add tooltip clearly explaining what this is, and/or consider renaming the label

Can we have @loriewhitaker scope for UX research to identify the best solution approach to make this more understandable? and possibly combine UX research and solution for %12.2 if small enough?

Read through the issue here.

How confident are we that we know what is causing the confusion with the label? Have we determined what our documentation should say to clarify the use of the label?

@cstasik can you create a research proposal? that helps me figure out how much time I'll need to help you guys out.

Some of the assumptions we have so far:

The documentation does not provide enough understanding of what a Detached pipeline is
The documentation does not provide enough understanding of what the Detached label means
The app UI does not provide references to the possibility of a pipeline being Detached
In the app UI, the Detached label does not provide sufficient meaning to users
In the app UI, the difference between Detached and Regular pipelines is not clear

Some of the comments that note confusion related to this feature I found on Slack:

removed [deprecated] Accepting merge requests label

added Category:Release Orchestration label and removed Category:Continuous Integration label

assigned to @rverissimo

Here is the UX research issue to clarify our questions related to this functionality https://gitlab.com/gitlab-org/ux-research/issues/244

mentioned in issue #62703 (moved)

added UX debt label

Issue Herder Results:

Vladimir Backend N | Frontend S |
Jason G Backend N | Frontend M | Needs UX | Needs Product |
Filipa Backend S | Frontend M | Needs UX |
Nathan Backend N | Frontend S | Needs UX |
- The issue states the problem ("The detached label is confusing"), but doesn't provide a concrete solution to this problem. We'll need to figure this out before any real development can happen on this issue.
Shinya Backend M | Frontend M | Needs UX | Needs Product |
- We have to investigate where the confusion comes from at first. I assume detached label itself is not entirely wrong as it correctly states the pipeline status, however, it's not intuitive for some users are not familiar with the detached word, which is Git specific term.

Marking Deliverable for %12.2. Not assigning backend for now, but we can adjust if our research uncovers backend work to be done.

Thanks for posting this here! We have a UX research issue pending to clarify those questions and help us identify the root cause of the confusion, and propose UI improvements before moving forward with design deliverables https://gitlab.com/gitlab-org/ux-research/issues/244

added Deliverable label

removed direction label

changed the description

This issue is marked as deliverable for 12.2 but it depends of UX research, which was moved to the backlog. How should we proceed? https://gitlab.com/gitlab-org/ux-research/issues/244

Edit: This issue should be moved to backlog. See https://gitlab.com/gitlab-org/gitlab-ce/issues/62137#note_194035009

It looks like a potential usability study (mentioned in ux-research#244) would get us what we need to confidently move forward with this issue. If that's the case, is it something you (@rverissimo) or @mnichols1 can take on?

Recruitment is likely my biggest question here. When can it happen?

I can take the UX research on, but we need to scope and prioritize it (@ogolowinski @cstasik). I'll need @loriewhitaker 's mentoring

@vkarnes for recruiting, it looks like any Gitlab user, who deals with pipelines, can provide feedback for this one, which makes it easier to find people!

@rverissimo and I spoke about this a bit and what we came up with was:

Have a user go through the current detached state process and documentation to get baseline information on what is confusing them
Have them then go through the same process in a prototype (can be an Invision one) which presents a better way of communicating the detached state, along with linking the appropriate updated documentation to find out if it better explains the situation.

@rverissimo I'm happy to help co-create a discussion guide for this and find users for you. We could use internal Gitlabbers to provide feedback (which should even be a faster recruit), however I'm not sure if they would be biased for this task or not - what do you think?

Perfect. Maybe recruit GitLabbers who do not work in the CI/CD stage groups to avoid some of the potential bias? Their feedback is welcomed of course but we can target those who use pipelines but aren't the ones who also build them.

@cstasik on Slack:

In that case, let's put it in the backlog and prioritize after the UX research is done

cc @nfriend

@cstasik As this is release orchestration, leaving the decision up to you

Can we do something obvious in the short term to make this more clear? Maybe just add a hover text?

@jlenny The question here is why and what we want to fix. We want to understand why people are having problems with this functionality, as well as to improve the documentation. See research issue here https://gitlab.com/gitlab-org/ux-research/issues/244

@rverissimo the basic question we want to clarify here is "why do my pipelines have a detached label with no explanation".

mentioned in issue gitlab-org/frontend/release-kickoffs#5 (closed)

Changed category label

added Category:Continuous Delivery label and removed Category:Release Orchestration label

@rverissimo @ogolowinski and I discussed consolidating this to do a consolidated clean up and review of how we explain Merge Trains, detached state, and pipeline with merged results. Since @ogolowinski has Merge Trains she is taking this under that effort to make the changes more fluid. @rverissimo I think your suggestion is correct on getting more input from customers to decision the actual effort to "clean up".

@ogolowinski @dosuken123 and customer support might be able to help you find the right issues and customers to chat with.

I will look into the UX research issue and see how I can prioritize it for UX on 12.2 https://gitlab.com/gitlab-org/ux-research/issues/244 fyi @ogolowinski

Setting ~"group::progressive delivery" based on ~"continuous delivery".

added grouprelease [DEPRECATED] label

Meeting notes - @ogolowinski @rverissimo

Current state is: When enabling pipeline for merged results, merge trains is enabled by default.
Can we have a detached pipeline with a merge train? In this sense, what is the meaning of detached?
How are the detached pipelines being used?
UX research: We can start with internal users first https://gitlab.com/gitlab-org/ux-research/issues/244#note_194168071
- @rverissimo to tackle the research issue.
Can we finish this for 12.2?
- Rayana: Not sure, because it depends on research, tech writing, and dev.
Low hanging fruit: Let's work together with research and tech writers to identify and implement improvements. Front-end to analyse and tackle it.

Can we have a detached pipeline with a merge train? In this sense, what is the meaning of detached?

Technically, detached pipeline is related to Pipelines for merged results, not directly to Merge Train. All pipelines run on merge trains are Pipelines for merge train, not detached merge request pipelines.

Answer from Shinya on Slack (private)

Updated the scope for UX research (usability testing) here. https://gitlab.com/gitlab-org/ux-research/issues/244 Please have a look!

changed the description

@rverissimo I updated the proposal bit - but I think it needs your touch for explaining what the tooltip should look like - c an you take a look

@ogolowinski I'd suggest not touching the documentation with this change, as we are doing the UX Research and want to figure out the best way to approach the improvement and discover what's necessary to make the workflow better https://gitlab.com/gitlab-org/ux-research/issues/244

I've updated the issue description, please double check!

@rverissimo when you say not touching the documentation , do you mean that you wish to skip the tool tip?

No, I mean not make any updates to the documentation page for it. This touches more than pipeline for merged results (since we started with merge trains now) https://gitlab.com/gitlab-org/ux-research/issues/244 and we don't have the answers to it yet.

Latest proposal, saved for posterity

Click me to collapse/fold.

Here is the UX research issue to clarify our questions related to this functionality https://gitlab.com/gitlab-org/ux-research/issues/244

Problem to solve

The "detached" label on pipelines is not clear and needs a rethink so that the UX is clear. The detached state means that it was a merge request pipeline, so ran in the context of the merge request, but did not run "attached", which means against the merge request result. The label serves to drive awareness of this status, but is mainly creating confusion now.

The documentation is also insufficient and does not explain this correctly. It only says Pipelines tagged with the detached badge indicate that they were triggered when a merge request was created or updated. and then a bit further down the following:

There are some cases where creating a combined ref is not possible or not wanted. For example, a source branch that has conflicts with the target branch or a merge request that is still in WIP status. In this case, the merge request pipeline falls back to a “detached” state and runs on the source branch ref as if it was a regular pipeline.

The detached state serves to warn you that you are working in a situation subjected to merge problems, and helps to highlight that you should get out of WIP status or resolve merge conflicts as soon as possible.

We also have confusing messages like the following:

Intended users

This is a broad set of users who interact with pipelines. They can see the status and be confused.

Further details

Originally implemented in https://gitlab.com/gitlab-org/gitlab-ee/issues/7380 and documented at https://docs.gitlab.com/ee/ci/merge_request_pipelines/#pipelines-for-merged-results-premium.

Proposal

For the first iteration: Add tooltip clearly explaining what this is, and/or consider renaming the label. Update documentation to be more complete at the same time.

Tool tip - show a warning sign. Detached label is meant for showing users a warning message that their MR state is not mergeable thus their code is tested against the source branch instead of merged results. Ideally, their MR should be tested against merged results because it provides more accurate results.

A more extensive solution will be proposed after UX research is conducted.

Permissions and Security

N/A

Documentation

As mentioned above, this does require a documentation update

Testing

There is possibility of UX testing to confirm this is more clear

What does success look like, and how can we measure that?

TBD

Links / references

changed the description

changed title from Improve clarity of "detached" label/state, merge request pipelines feature to Improve clarity of "detached" label/state in the merge request pipeline

changed the description

Slack channel for discussion: #f_detached_pipeline

changed title from Improve clarity of "detached" label/state in the merge request pipeline to Add tooltip to improve clarity of "detached" label/state in the merge request pipeline

Updated the UX proposal here https://gitlab.com/gitlab-org/gitlab-ce/issues/62137#ux-proposal. @ogolowinski @dosuken123 @nfriend could you please review?

fyi @vkarnes

@rverissimo looks good to me

Tentatively labeling this issue ~"UX ready"

added 1 deleted label

changed the description

Nathan is ooo until the 12th. @jhampton could you look into this issue please? Perhaps we can assign it to someone else since it's a minor FE update :)

@rverissimo We have quite a few frontend folks out, but I will reach out and see if anyone has capacity to address this tomorrow (Friday). If not, Nathan was planning on picking this up on Monday.

Thank you @jhampton!

@nkipling thank you for jumping in and creating a MR so quickly!

created merge request !31626 (merged) to address this issue

mentioned in merge request !31626 (merged)

changed the description

Updated tooltip text to be: The code of a detached pipeline is tested against the source branch instead of merged results

closed via merge request !31626 (merged)

mentioned in commit cdf347bf

@jlenny This item is a small incremental improvement - for the first phase we decided to solve this using a tooltip, next phase will be more comprehensive . Since this is a tool tip change, I am not adding it to the blog post. Is there anything that I need to do with it now that it is complete?

@ogolowinski agreed on not including this in the blog post. We'd normally only include direction and release post item issues anyway, so we're good to go here.

I'm wondering how much the new tooltip really makes things more clear. The description of this issue has the sentence The detached state means that it was a merge request pipeline, so ran in the context of the merge request, but did not run "attached", which means against the merge request result. which is pretty clear if a bit long. The new tooltip says The code of a detached pipeline is tested against the source branch instead of merged results, which feels a bit confusing to me because I think by code you actually mean source, and by tested you mean built or maybe run. Attached/detached doesn't really have anything to do per se with the build results/built code, and also isn't really tied to testing. It relates to the whole pipeline. Also, I feel like it's missing the name of the feature it's related to (pipelines for merged results) so if I saw that tooltip I wouldn't really know what to search for to look for more.

If it's not too late please double check.

@rverissimo Please review @jlenny's suggestion - can we change the tooltip text?

@ogolowinski @jlenny Looks like this change has already been merged in https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31626. But making another change to this text wouldn't be a big undertaking (although it probably wouldn't make it in time for %12.2)

@nfriend as far as I know from @darbyfrey the code freeze will be the 17th

Thanks for the feedback here @jlenny

We used this as reference for the tooltip update:

Detached label is meant for showing users a warning message that their MR state is not mergeable thus their code is tested against the source branch instead of merged results. Ideally, their MR should be tested against merged results because it provides more accurate results. https://gitlab.com/gitlab-org/ux-research/issues/244#note_199596672

Also, not only pipelines for merged results need to be enabled, but pipelines for merge requests need to be configured -- otherwise pipelines for merged results won’t run.

Here's a suggestion for a new update:

Pipelines for merge requests are configured. A detached pipeline runs in the context of the merge request, and not against the merged result.

Please review and feel free to suggest any improvements

The only thing I might add is "See our documentation for "Pipelines for Merged Results for more information on how to set up this feature."

@jlenny

Pipelines for merge requests are configured. A detached pipeline runs in the context of the merge request, and not against the merged result. Learn more on the documentation for Pipelines for Merged Results.

fyi @nfriend

(Ideally we would allow users to click and go to the documentation, but this is a good opportunity to prototype a better proposal during the ux research https://gitlab.com/gitlab-org/ux-research/issues/244#note_199596672 )

@jlenny @rverissimo Not to drag this out further, but I think we have access to the name of the source and target branch when showing these tooltips, so we could include these names if it made things clearer.

For example, if the source branch is my-feature-branch and the target branch is master:

Pipelines for merge requests are configured. A detached pipeline runs in the context of the merge request (on my-feature-branch), and not against the merged result (my-feature-branch + master). Learn more on the documentation for Pipelines for Merged Results.

Just an idea - feel free to disregard if this complicates things.

@rverissimo, just an FYI:

Ideally we would allow users to click and go to the documentation

I did a quick test - while we do have the ability to embed a link to the documentation inside the tooltip, we wouldn't be able to actually click it, since the tooltip disappears as soon as the user's mouse leaves the label.

I think we have access to the name of the source and target branch when showing these tooltips, so we could include these names if it made things clearer.

@nfriend IMO, the message looks a bit too long to be in a tooltip. But if there is a possibility to show the branch name, bringing more clarity to users, I see no harm. We can always learn from it during the usability testing in 12.3.

I did a quick test - while we do have the ability to embed a link to the documentation inside the tooltip, we wouldn't be able to actually click it, since the tooltip disappears as soon as the user's mouse leaves the label.

Yes, please disregard anything that adds more complexity to this -- such a link to docs etc. Let's keep the change to a minimum and iterate on it once we receive more feedback from our users.

Thanks for jumping on this, @nfriend!

I created https://gitlab.com/gitlab-org/gitlab-ce/issues/66061 to track this update, since this issue is already closed.

Thank you @nfriend!

mentioned in issue #66061 (closed)

mentioned in merge request !31917 (merged)

Add tooltip to improve clarity of "detached" label/state in the merge request pipeline

Problem to solve

Intended users

Further details

UX Proposal

What we will update

Where it needs to be changed

Permissions and Security

Documentation

Testing

What does success look like, and how can we measure that?

Links / references

Designs

Child items ...

Activity

Problem to solve

Intended users

Further details

Proposal

Permissions and Security

Documentation

Testing

What does success look like, and how can we measure that?

Links / references

Add tooltip to improve clarity of "detached" label/state in the merge request pipeline

Problem to solve

Intended users

Further details

UX Proposal

What we will update

Where it needs to be changed

Permissions and Security

Documentation

Testing

What does success look like, and how can we measure that?

Links / references

Relates to

Activity

Problem to solve

Intended users

Further details

Proposal

Permissions and Security

Documentation

Testing

What does success look like, and how can we measure that?

Links / references