Handle errors for real-time updates

Comment from: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8357#note_20845195

Regarding on where to proceed next with the flash messages, we already have a few places where we already have real-time updates right? For example, issue/merge request thread comments automatically appear. So I was wondering if we had some GitLab-wide design for these type of messages in general, some type of general design direction before diving into something specific. For example, would we design a flash message if thread comments fail to auto-update? And so should we work on that first instead of the flash message for failed title updates?

Let's understand the type of errors we can have with real-time updates, and a consistent way to approach that across GitLab.

Currently we don't show that we are polling since our loading spinner occupy the all screen and it would be annoying to have a spinning flashing every 30s. We do show an error message if the request goes wrong.

What should we do?

Places we already have real-time behaviour:

• Pipelines Table page
• Pipelines Table in Merge Request Page
• Pipelines Table in New Merge Request Page
• Pipelines Table in Commit Page
• Issue Title in Issue Page
• Deploy boards in Environments Table Page - EE

Places where we'll have real-time:

• Pipeline Graph in Pipeline show page - https://gitlab.com/gitlab-org/gitlab-ce/issues/25226
• Sidebar in Issue Page - https://gitlab.com/gitlab-org/gitlab-ce/issues/29982
• Sidebar in Merge Request Page - https://gitlab.com/gitlab-org/gitlab-ce/issues/29982
• Issue Description in Issue Page - https://gitlab.com/gitlab-org/gitlab-ce/issues/25049
• Merge Request Widget
• Issue and Merge Request State - https://gitlab.com/gitlab-org/gitlab-ce/issues/29978
• Comments and system notes - https://gitlab.com/gitlab-org/gitlab-ce/issues/30458

@victorwu: Created this issue to talk about handling errors in a consistent way across GitLab. Would be good to agree upon the goals. Quick first pass:

• As a user, I understand if my view of GitLab is real-time, live and updating or not.
• My regular use of GitLab isn't needlessly interrupted by errors that have no real meaning/impact to me.
• If my view is not live, I can easily find some help on how I might fix this, or some indication of what might be going on. Thanks!

mentioned in merge request !8357 (closed)

added ~874211 label

changed milestone to %Backlog

added ~897282 label

@awhildy : That sounds great!

1. I think you mentioned sometime ago that we should build trust with users so that they expect most things to be live-updating, and we don't need to be too explicit about this, and I think it was in the context of saying spinners are not a good idea. Does that apply in this context? Should users have clear understanding that an entire page is live updating or certain parts of the page? Or is it enough that they just have a general feeling / concept, but not explicit understanding?

2. I agree with the needlessly minute errors. But to what degree and granularity? Is it sufficient to describe a generic "connection error"? Do we need to be explicit to say your Internet connection is broken? GitLab is returning errors? GitLab is down?

3. It's not clear to me under what circumstances to display these error messages? With a lot more polling / socket connections in the future, do we just have some high-level notion of error / connectivity, and that's sufficient to expose to the user? Surely we don't need to say that we couldn't update the labels in your view, so now refresh your page.

4. There's really not much the user can do recover, beyond refreshing the page or checking their Internet connection, both which seem archaic things to ask a user to do. I think Google properties like to keep trying and there's a countdown to tell you when the web app will next try. I don't particularly like that design. But it's not terrible either. Are there any best practices here? What would be appropriate for something like GitLab?

Thanks @victorwu!

1. I think it applies in this case. The goal is that we get to the point where everything is live-updating. At that point, users will be able to trust that things are real-time. The tricky part is the transition. It will be a little bit messy. But I'd really be concerned about putting indicators next to everything that is real-time, thus cluttering up the experience, distracting users from the work they are trying to use GitLab for. Plus removing things is always harder than adding things. Ideally, in the transition, we clump the work so that logical things are real-time. It may be a happy surprise sometimes to people when things update live. I don't think that is a problem, though.

2. Errors that are important are ones that

• A user has to take an action on to continue their desired flow
• Will cause some action the user plans to do to be wrong When a user needs to take an action, we should show the error, and show as much information we can (or link to documentation) to help them know what to do.

3. Perhaps? If possible, I'd rather only show something when there are errors, instead of always show connection status, though. Consider how Slack handles it. It throws up a flash message when there are errors with a connection. Totally agree that we should have a consistent place where we show connection errors, though.

4. Retrying might be the best way to do it. Would love to understand what you don't like about Google's design with it -- maybe we can address those concerns. I think we could also add a link to documentation for if the problem persists. That way we can include those sort of archaic suggestions (check internet connection and/or refreshing) without it having to be front and center. We should also think about what troubleshooting steps people who have their own install of GitLab should consider.

removed ~897282 label

mentioned in issue #31227 (moved)

closed

Great content here, but closing as duplicate of https://gitlab.com/gitlab-org/gitlab-ce/issues/31227 since we've come to a solution there for now.