[META][UX] Improve the process/screens/errors/warnings when upgrading from (mostly vanilla) D7

[klonos]

I am starting to perform mostly vanilla D7 -> Backdrop upgrades, and noticing things that should be fixed and others that could be improved. I'll be using this meta-issue as a means to take notes/screenshots, and then file separate issues to address these problems.

Process (steps used to perform the update)

I plan to improve these steps, to include most common modules/settings (for example installing Views 7.x and other 7.x modules that have been merged into Backdrop core). For now though:

1. Install a vanilla latest D7 site.
2. Enable showing all error messages.
3. Install admin_menu 7.x
4. Disable the following modules:
   • Help
   • Overlay
   • RDF
   • Toolbar
5. Clear caches
6. Clear recent log messages
7. Export the D7 database
8. Setup a vanilla latest 1.x Backdrop site (do not install it) - Follow the instructions in https://docs.backdropcms.org/documentation/upgrading-from-drupal-7-steps and fix/improve them as you go (issues about those documentation pages should go against Address feedback on the "Upgrading from Drupal 7" documentation backdrop-ops/docs.backdropcms.org#126).
9. Import the D7 database into the Backdrop site
10. Adjust settings.php on the Backdrop site
    • database credentials should match those of the D7 database
    • set $settings['update_free_access'] = TRUE;
11. Run update.php on the Backdrop site, follow the prompts, add tasks here

Possible UX improvements

• Following the documentation, before I exported the D7 db, I removed certain D7 core modules that I knew that they have been removed from Backdrop core, with no alternatives for them existing in contrib (I'm referring to things like Help, Overlay, RDF, Toolbar). What happens when that step is missed though? Are there any errors? I'm thinking that we should be handling these in a graceful or even transparent way, even if the user skipped the step to disable/uninstall them on the D7 site pre-upgrade.
• Final report with messages from update hooks:
  • Not clear if these are status/warning/error messages
  • The human-readable versions of module names should be used
  • The "fix transliteration files" message/link should only be shown if there are indeed files to be transliterated.
    [screenshot]

Errors & bugs

• After importing the D7 db in the Backdrop site, and adjusting settings.php (db credentials + $settings['update_free_access'] = TRUE;), you are meant to run update.php. What happens if you don't though? (remember: users may not be as technical, and they might not be reading the extensive upgrade instructions documentation) ...I tried simply visiting the URL of the site, and this is what I was greeted with:
  
  At this point:

  • settings.php has not been updated - it's just the OOTB defaults:

    $config_directories['active'] = 'files/config_' . md5($database) . '/active';
    $config_directories['staging'] = 'files/config_' . md5($database) . '/staging';

  • basically the error is not communicating reality, which is that the config directory is not created at all. The message shows what Backdrop is about to create, or would create, if the logic was a bit "smarter".

  What I would expect in this situation is that Backdrop would be able to detect that:

  • The database is D7, about to be upgraded to Backdrop.
  • The config directory has not been created yet.

  If the above 2 things are true, then:

  • Create the config directory.
  • Update $config_directories in settings.php
  • Redirect me to `update.php.

• Error after logging into the freshly-upgraded Backdrop site for the first time:

  Warning: file_put_contents(public:///.htaccess): failed to open stream:
  "BackdropPublicStreamWrapper::stream_open" call failed in file_save_htaccess()
  (line 515 of /app/docroot/core/includes/file.inc).
  

  
  There was an error of type security logged, with referrer being admin/config/media/file-system/transliteration and location ?q=admin/config/media/file-system/transliteration.
  This was most likely because I have intentionally skipped creating a sites/default/files directory. But when I checked my local, the directory was created, and the .htaccess file was there as well.
  Noting that:

  • the site has now resulted in having both sites/default/files, as well as the files/config_[blah] with active/staging it.
  • admin/config/media/file-system shows sites/default/files as "Public file system path"
  • ...

• Instead of the expected "Content" top-level menu item in the Admin Bar, there is now an "Add content" top-level menu item with no icon. That's because Views is not enabled. Shouldn't it though? (see https://github.com/backdrop/backdrop/blob/1.x/core/modules/views/views.info#L9 where required = TRUE is set)

• Because Views is not enabled, the "User Accounts" top-level menu item is also missing from the Admin Bar ...how am I to manage user accounts then? 👎🏼

• Attempting to enable Views (Views UI actually, as the Views module is hidden) -> I get the usual confirmation about the Views module being a dependency -> I confirm -> error:

  DatabaseSchemaObjectExistsException: Table cache_views already exists.
  in DatabaseSchema->createTable() (line 661 of /app/docroot/core/includes/database/schema.inc).
  

  
  🤔 ...if the cache_views table already exists, it means that Views must have been enabled at some point during the Backdrop upgrade (the 7.x contrib module wasn't installed in the D7 source site), then for some reason disabled ...anyway, since I have no site/UI now, I attempt to refresh the page -> I get a browser error about submitting the data again (scary - bad UX) -> I confirm -> I am redirected to the modules page, where there is a series of errors, repeated 5 times:

  Warning: array_filter() expects parameter 1 to be array, null given
  in views_get_enabled_display_extenders()
  (line 514 of /app/docroot/core/modules/views/includes/utility.inc).
  

  
  ...but there's also a green "The configuration options have been saved." message 👍🏼 ...and Views/Views UI are both enabled 👍🏼 ...and all the expected menu items are shown in the Admin Bar 👍🏼