Group-income-simple: Standardized error messages in scoped banners

[taoeffect]

Problem

In #779 we began to tackle the problem of user-facing error messages more seriously, by adding generalized tools to our disposal (the addition of the new scoped banners).

However, the error messages that are being shown to users in that PR still can be improved. For reference, here's what they looked like:

this.$refs.formMsg.danger(L('Failed to upload the group picture, please try again. {codeError}', { codeError: error.message }))

Or the more verbose 3-liner:

this.$refs.formMsg.danger(L('Failed to upload the group picture, please try again. {codeError}', {
  codeError: error.message
}))

There are a couple problems here:

1. "Please try again" is not good advice to give to the user. Trying again almost always results in failure, with the same error being displayed. So we should be telling them something more helpful than "try again".
2. There is inconsistent repetition with the variable that's being used to display the more detailed error message, where the variable is somethings called codeError and sometimes named something else. Furthermore, { codeError: error.message } is unnecessarily long.

Solution

Replace all scoped banner error messages with error messages that follow the following conventions.

To address problem 1, error messages should tell the users to do something useful. Something useful would be to send us a bug report along with all the information we need to debug it (or to follow an existing, open issue).

We can accomplish this by telling users to visit the debug page as suggested here.

To address problem 2, we can use an LError function to create a standardized error object.

So this:

this.$refs.formMsg.danger(L('Failed to upload the group picture, please try again. {codeError}', { codeError: error.message }))

Becomes this:

this.$refs.formMsg.danger(L('Error uploading group picture: {error}. {troubleshootLink}.', LError(error)))

Where LError is a helper function that returns an object that looks something like this:

function LError (error) {
  return {
    error: error.message,
    troubleshootLink: L('{link_}Click to troubleshoot{_link}.', {
      'link_': `<router-link class='link' :to="{ path: '/debug', query: { error: '${error.message}' } }">`,
      '_link': '</router-link>'
    })
  }
}

• Note that this depends on #595 being closed
• Also the Style Guidelines.md documentation needs to have its example updated
• The debug page can use the passed in error query parameter to generate a draft of a message that the user can submit to us

[sandrina-p]

I agree with this approach. It's a mature solution based on all our previous discussions during #779

[sandrina-p]

@taoeffect you say:

The debug page can use the passed in error query parameter to generate a draft of a message that the user can submit to us

I don't remember this scenario being designed by @mmbotelho. I implemented the logic for it but with a very raw design, but I was hoping @mmbotelho could make it better. Also, I think this page is lacking some instructions for the user to send us the logs.

[taoeffect]

Agreed that will probably need some iteration later on from @mmbotelho, but for now what you show in the screenshot looks great (I think! will need to review!). Part of this will be affected by how they will submit errors to us — i.e. depending on whether we go with a community forum, and if so, which software, etc.

[sandrina-p]

@taoeffect I have a question about Application Logs page: What if, instead of asking users to download and send us the report, we have just a "Send report" button for them to click and it would send the JSON to somewhere to our servers?

[taoeffect]

@taoeffect I have a question about Application Logs page: What if, instead of asking users to download and send us the report, we have just a "Send report" button for them to click and it would send the JSON to somewhere to our servers?

I think that's a good idea, and we should also make sure they can download and send us the report as well. In other words, users should be able to decide whether they want to automatically send us everything, or whether they want to send us a redacted version of what went on in their group.

For now, let's just stick with download and send for the following reasons:

1. We do not have such a server/infrastructure implemented for receiving reports
2. If we did, we would need to additionally integrate it somehow with a ticketing system / bug reporting system / forum / etc., and we also don't have that yet either