Add guidelines for error handling

I have looked through our current guidelines and I couldn't find anything relating to error handling, forgive me if I've missed something.

There are plenty of things that can go wrong when you're crushing the devops cycle. We need to be helpful with our error messages and guide the user to a resolution as best as we can.

In an open MR (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22458#note_115879542), I am converting an existing feature to a vue application, I am struggling to find direction on improving the errors we show to the user on the clientside. I'm not sure how to handle this in a sensible, standardized way.

Luckily, we can solve this.

UX can document how errors should look and behave. Are there guidelines around "good error messages" that could be written?

BE can document how errors should be returned for endpoints that FE will consume and develop the modules/utilities for simple implementation.

FE can document how errors should be caught and displayed, and also build modules/utilities for simple implementation.

  • UX, BE and FE discussion
  • UX design system guidelines
  • BE documentation and utilities
  • FE documentation and utilities

I'm happy to have a group call to put this on the right path, leave a comment or ping me on slack.

Update 1

09/11/2018 22:00 UTC

Firstly, thank you for your input.

So, it seems like we're actually mostly there.

What do we already have?

UX has conceptualized and documented the toast component for system messages, and it looks like that may be our main UI pattern for errors. https://design.gitlab.com/components/toasts FE has started a vue toasts implementation issue at gitlab-ui#76 (closed).

FE has documentation on how we will consume endpoints using vuex actions and subsequently how we will store errors from a given HTTP client in a vuex store, ready for use in a vue application. https://docs.gitlab.com/ce/development/fe_guide/vuex.html#actionsjs

FE has another issue for documenting JS error handling in https://gitlab.com/gitlab-org/gitlab-ce/issues/36064#note_63545903 that includes discussion regarding clientside sentry reporting through raven, which should be an option for each error caught.

FE has a vanilla createFlash utility for displaying a flash banner, our current implementation of error handling (big red bar, or blue for info, at the top of the page). https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/flash.js#L70

What is left to do?

  • UX should document their opinion on errors explicitly. We have design system component docs for toasts, but we should document how to use toasts for errors specificially. Should we use toasts for every type of error? Should error toasts look the same as info toasts?

  • BE should document a schema for returned errors and other guidelines about raising/responding with errors. What response payload should we expect on the clientside to handle errors in a standardized way? How should we declare the severity of an error? HTTP status codes are standardized and useful, but we still need to define how/which error messages are presented to the clientside.

  • FE should then document how we handle those new standardized errors on the FE, with the vuex actions, toast component, flash utility included.

  • FE should update the createFlash utility to be the vanilla implementation of toasts. Hopefully then the vue component can use the vanilla utility for it's logic whilst it is fazed out and combined into a single implementation.

Edited by 🤖 GitLab Bot 🤖