Show notice in the admin UI when .htaccess, robots.txt, or settings.php have been updated in a release, and either link to instructions, or auto-update when safe/possible

[yorkshire-pudding]

Description of the need

The documentation for updates is based around a manual update on the server. However we have an updater in the UI, which many people will use to update Backdrop.

The upcoming release, 1.24.0 includes an update to the .htaccess file in the root directory (likely to have changes) and the .htaccess file in files/ and the release notes for the preview state:
'The .htaccess file has been modified to include settings for PHP 8. (See #5906)'

Site owner who just use the updater might not see these release notes and may not know.
@klonos has suggested on Zulip that the updater will only update the core folder so at least customisations won't be broken, but how should they get the updates?

Proposed solution

Site owner should be guided through updating the files without losing their customisations.
Not sure how best to do this.

[klonos]

AFAIK, we have facilities/functions to be updating the settings.php file (that's how details about the database connection and config files directories are bing added to the file during installation). Adding things that don't exist should be easy, but things like updating inline comments, taking into account any linked settings files like setting.local.php, they'd be tricky.

And settings.php is a php file, so we could use linked (include'ed) files, but .htaccess and robots.txt are very specialized files, and they don't allow for a default and a customized version to coexist. So, I think that trying to automate this would be a very difficult if possible at all business. The best we could do is figure out a way to version these, and perhaps let people know via a notice in their status page that they should review and make manual changes.

Another thought is that we could be replacing these files automatically during updates, but only after checking and making sure that they have not been modified compared to the previous "vanilla", core-provided respective file.

In the case of #5906 we could add a check for when the php version used is v5 or v7, and also check if the added section in the existing .htaccess file is present or not, then throw a notice in the status report, along the lines of "your existing .htaccess file is lacking support for PHP v8 - certain things may not work as expected - you will need to update it manually - here's a link with more details". But this is very specific to this use case - not a generic, reusable thing. Point being that we may be able to do something on a per case basis as these files are being updated.

Would love to see what others think, and if you have any other ideas.

[yorkshire-pudding]

Possibly the solution is more about documentation and giving details about what has changed, rather than update everything and account for every edge case. For the recent .htaccess changes, it should be enough to say here is what we've added and this is where we added it; the easiest thing is to copy this into your .htaccess file on this line. Can we show a notice after we've updated? Can we have a notice in Backdrop news on the Dashboard? Can we have custom messages in the release notifications?

[olafgrabienski]

Site owner who just use the updater might not see these release notes and may not know.

I agree, and I see it as a general problem regarding updates with breaking or important changes, be it core or contrib. There are links which point to the release notes on admin/reports/updates and admin/config/system/updates, but as you say, people might not see (or consider) them.

A custom message in the updater pages, near the number of a recommended release link, sounds promising. But wouldn't it just repeat (part of) the release notes?

My idea: a special category for releases which require subsequent and/or manual changes. Releases of that category would be styled differently, comparable to security updates, but less alarming, e.g. using the blue for info messages and maybe also highlighting the link to the release notes.

[yorkshire-pudding]

My idea: a special category for releases which require subsequent and/or manual changes. Releases of that category would be styled differently, comparable to security updates, but less alarming, e.g. using the blue for info messages and maybe also highlighting the link to the release notes.

I like that idea!!

[klonos]

What about the idea of auto-updating these files if they have not been customized? ...although we'd need to figure out a way to know what the vanilla/uncustomized versions of these files are 🤔 ...thinking of some ways to version them, or checksum them perhaps?

Anyway, auto-updating these would solve half of the problem ...there wouldn't be a need to let people know what has changed nor what needs to be done (because there would be nothing to do).

[olafgrabienski]

The issue was discussed in the Developer Meeting from 2023/01/05, main idea: combine auto-updating of non-customized files and adding a message about file changes:

https://youtu.be/RHhOwC8VHlg?t=638

[klonos]

In case we want to do some advanced parsing and want to use something already created, here's an open source (Apache License 2.0) htaccess parser: https://github.com/tivie/php-htaccess-parser

[yorkshire-pudding]

Just to add to this discussion, I've added a thought to the auto-update ticket at #5929 (comment)