fix(db-updates): provide users with actionable steps to resolve db-updates issues

[Benunc]

User Story

As a give administrator, I want clear error messages with actionable steps to take in the event of database update stalling out so that I can resolve it myself, or if I need to escalate it to support, I can give the support technicians a head start.

As a support technician I want to limit the number of tickets that are database update-related and help only the customers whose servers/web hosts are really not letting them run db updates.

Current Behavior

I (the user) currently am greeted with "please contact support" or database updates that simply do not complete.

Expected Behavior

I expect for database updates to fail gracefully, and provide me with several options to resolve the issue myself before contacting support.

Possible Solution

1. In Core, if something fails or stalls, users should get an error message that points them to a documentation article where we talk about the [DB Health Check plugin] (https://github.com/WordImpress/Give-Database-Healthcheck) as well as outline as many possible solutions to database updates stalling as possible. (I will create that issue next and edit this comment with it soon)
2. If the DB Healthcheck update stalls, then it gives REAL ACTIONABLE error messages like:

Give was not able to access admin-ajax and cannot run the necessary update to add the Sequential Ordering table. Contact Give Support and tell give them this error message.
Or
Changes Give made to the database were prevented for an unknown reason. Ask your host about disabling database caching and contact Give Support and give them this message.

Acceptance criteria

• The simple "please contact support" error message is nowhere in core
• The error message links to the newly created doc on DB updates
• The error message is as verbose as possible to point to the actual cause of the issue stalling the updates

Related:

https://secure.helpscout.net/conversation/587252948/19027/

[kevinwhoffman]

@Benunc @mathetos Please correspond with @ravinderk and/or @raftaar1191 to decide the communication for DB errors.

[mathetos]

I'll meet with @ravinderk on this soon and we'll report back here with a call summary.

[mathetos]

Call Summary
Participants: @ravinderk @mathetos

Consensus is that the current error message is the only place in which we can ensure that there is an actual problem. It is a vague error simply because we don't yet have enough information to know with certainty exactly why the DB update fails; it could be a lot of different things. In order to add better logic we need more information. We can't yet perfectly replicate DB update problems with Memcache for example. We can't yet perfectly replicate DB update problems with admin-ajax exactly as it happens in some of these environments. We don't know what types of server security prevents the database tables from being created. Without this information we can't have logic in the plugin that checks for these problems and gives better error messages.

To that end:

1. Matt will provide better wording for the existing error message, which will link to documentation that @Benunc is currently writing.
2. Matt will connect with Support and Devs at WooCommerce to see whether they face similar issues and what they do about it.
3. Ravinder will research the issue more in terms of how Woo/EDD deal with these from a code perspective.
4. For the next couple weeks, whenever @Benunc gets a DB update issue he should first ping Ravinder to work on it so Ravinder can see more environments with as many different scenarios as possible.

That's our plan moving forward. For this issue, let's keep it focused on a better error message that points to existing docs (that are not yet finished).

Docs issue here:
https://github.com/WordImpress/Give-Docs/issues/174

[kevinwhoffman]

Per dev team discussion, for 2.1.5 we will add @Benunc documentation link to any error that appears during DB update. We will look into further improvements in future releases.

[mathetos]

This is the shortlink for that new Doc as a reference:
http://docs.givewp.com/troubleshooting-db-updates

[ravinderk]

@mathetos Link added to notices