Document what the existence of the PACKAGE_MANAGER_FAILURE.yml means

Problem/Motivation

In #3357941: Write helpful message to FailureMarker if script execution time was exceeded during stage life cycle the FailureMarker was going to be used if there were time outs must of which would not leave your code in an indeterminate state which is the purpose the FailureMarker file.

We document in the class doc but we should probably document that elsewhere.

If the PACKAGE_MANAGER_FAILURE.yml exists probably the only thing you can do is restore your code from a backup. We intentionally made this a file instead of using Drupal state service because depending which files did not get copied over you site might not even load. In this case the docs should let the user know that they should check for this existence of this file.

Proposed resolution

Lets document this in several places

1. package_manager.api.php
2. In https://www.drupal.org/docs/8/update/automatic-updates
3. Project Browser docs?