Inform users that the maintenance mode message is not displayed on cached pages

Hi,
I tried to replicate this issue but I did not find any. I followed the steps below.

1. I installed an instance of drupal-8.1.8.
2. I put the site in Maintenance mode.
3. I upgraded the version to drupal-8.1.10.
4. disable the maintenance mode

It worked fine in my system. Can you please describe specific steps you followed?

Re opening this because this is a problem a lot of people ran into, see https://www.drupal.org/forum/support/post-installation/2017-06-10/drupal...

There is a problem here because some of us want to be able to use maintenance mode to hide a site. (what's the point of having a maintenance mode feature if pages are still showing after it's enabled?) I think it is poor UI to have the maintenance mode message phrased this way

It is not obvious that an additional step of cache clearing is needed.

The UI may need an additional checkbox "Flush caches to actually get it into maintenance mode".

Some loosely related issues I found:

• is the /user page may leak blocks you don't want visible: #722434: Stuff still visible at /user when site is offline (Maintenance mode)
• #1177680: Change the "Put site into maintenance mode" checkbox to a button. make it easier to engage maintenance mode (UX)
• broken link in update.php sometimes #2830326: Broken link to 'Put your site into maintenance mode' on update.php results in WSOD
• easier to login? #341624: Add login details to default site maintenance message.

It's very confusing, that your site is not in maintenance mode until you flush the cache. Also the form is confusing. Because the checkbox is not enabled until you flush the cache. There should be a message like "You must flush the cache to get into maintenance mode".

Setting the priority to "Major", because the maintenance mode is a crucial core feature and exists since Drupal 8.0.

+1 there should be a message or the cache should be flushed when saving

I have implemented the cache flush after the maintenance mode has been enabled. Please review.

Discussed this with @Peter Majmesku and @webflo during the Global Sprint Weekend. @webflo brought up the point that it might actually be OK to still serve cached pages without flushing it. It seems that only Page Cache is affected by this, I was not able to reproduce this issue with Page Cache disabled.

@Peter Majmesku brought up that this still might be confusing for people, so we thought it would be good for Page Cache module to form-alter a notice to that form warning about this behavior.

+++ b/core/modules/system/src/Form/SiteMaintenanceModeForm.php
@@ -103,6 +103,10 @@ public function submitForm(array &$form, FormStateInterface $form_state) {
+      drupal_flush_all_caches();

Flushing all caches is not necessary imo. The "'http_response" cache tag should be sufficient.

Here's a different patch, which displays an info regarding necessary cache flush for showing up the maintenance mode message to users. Please review.

Removed unnecessary if-check from patch and added string to not break translation.

+++ b/core/modules/page_cache/page_cache.module
@@ -29,3 +30,10 @@ function page_cache_help($route_name, RouteMatchInterface $route_match) {
+  $form['maintenance_mode']['#description'] .= ' <p>' . t('Since the page cache is enabled, you must flush the page cache to display your maintenance mode message to site visitor. Visit the <a href="@performance-page-url" title="performance settings page">performance settings page</a> to flush the page cache.' . '</p>', ['@performance-page-url' => Url::fromRoute('system.performance_settings')->toString()]);

I think the explicit toString() is not necessary, it will be cast to string automatically.

Also adding a screenshot for some review of the interface text hopefully by a native speaker and tagging accordingly.

Removed toString() call.

Here's the screenshot. May any native speaking person would review the spelling, please?

Since the page cache is enabled, you must flush the page cache to display your maintenance mode message to site visitor. Visit the performance settings page to flush the page cache.

Thanks, the patch looks good to me!

patch #17 works for me

This problem comes from the page-cache in combination with the maintenance mode - It probably will also happen when maintenance mode is set from drush. (Does drush clear caches when switching to maintenance?)
I wonder whether it would make sense to switch off page-cache completely when the site is operating in maintenance mode?

I guess there are two different reasons for setting maintenance mode. The main use case is IMHO to disable possibly broken functionality while running updates. Unless page cache would be broken too, it seems like a good thing that cached responses are still returned.. it means you have fewer non-working page requests.

If you're using it to somehow on purpose disable a site then you might want to stop serving cached pages, but something like the proposed message seems good enough to me, force-clearing the cache or disabling page cache seems problematic and would result in more downtime, also for (large) sites behind reverse proxies that propagate cache clears to that proxy. I think in almost all cases, you want to have as little actual downtime as possible.

Since the page cache is enabled, you must flush the page cache to display your maintenance mode message to site visitor. Visit the performance settings page to flush the page cache

1. We need to use an article such as "the" or "a" for the singular "to site visitor". At the moment it reads like "site visitor" is the name of something. Or, in my opinion, we can omit the article and use plural.
2. Should "performance settings" be capitalized to match the schema label for system.performance, or match the page title which is "Performance" only?

Some Bike shedding:

I wonder if it's okay to omit the first part of this sentence as well in order to keep the message/sentence short.

"You must flush the page cache to display your maintenance mode message to site visitors."

Or if it is necessary, then sometimes it reads better with the explanation at the end of the sentence.

"You must flush the page cache to display your maintenance mode message to site visitors since the page cache is enabled." puts the instructional part of the text.

Problem is reproducible and I believe is important.
As for me adding additional comment (with obligation for site maintainer to clear cache) for now this is work around.
It should be fixed properly.

We (Dresden: pminf,mmbk,akoe) believe that the cache should be flushed automatically.
If the administrator MUST flush the cache, to prevent front-end users from accessing the site, there seems to be no reason to make this optional and ask him to flush the cache.

Convinced, it's better to leave available as long as possible

SORRY

Here is patch that could solve problem. Will wait tests.
I have found that this is just solution. And actually for now this is not cover executing by drush. I will do this later. So we have to invalidate cache properly moment (on state change or configuration update).

@mradcliffe #28: Thanks! I have improved the spelling according to your suggestions.

Also I have improved the code, for not breaking tests.

@Chewie: As @Berdir wrote in #27 it's important to not flush the page cache in any case. Because the site owner might want to have as little downtime for pages as possible. When maintenance mode is enabled, the pages will be delivered from the page cache. If you do not want this, you must flush the page cache. Therefor I have created the patch.

That's how the maintenance page will look like after my patch has been applied:

Yes, for updates, there is no reason to force visitors to see the maintenance method. If they still get a cached working page then that's a good thing, I don't understand why you think differently?

OK, looks good to me. I think #28 was sufficient textual review I think, so marking RTBC.

Tagging for usability review for the new text.

I think the issue title here is misleading. Maintenance mode is enabled - it's only the maintenance mode message that is not being displayed because the cache is hit. I suggest something like Inform users that the maintenance mode message is not displayed on cached pages - also the issue summary needs updating to reflect that.

Also I think there possibly should be further discussion about the multiple uses of maintenance mode. I think that this bug report has arisen from the expectation that you can use the maintenance mode to mothball a site whereas its intended purpose it give the site a small window to make updates before coming back online. Therefore it is developed in such a way to preserve the appearance of a working site.

+++ b/core/modules/page_cache/page_cache.module
@@ -29,3 +30,11 @@ function page_cache_help($route_name, RouteMatchInterface $route_match) {
+/**
+ * Implements hook_form_FORM_ID_alter().
+ */
+function page_cache_form_system_site_maintenance_mode_alter(&$form, FormStateInterface $form_state, $form_id) {
+  $form['maintenance_mode_message']['#description'] = t('Since the page cache is enabled, you must flush the page cache to display your maintenance mode message to the site visitor. Visit the <a href=":performance-page-url" title="performance settings page">Performance Settings page</a> to flush the page cache.', [':performance-page-url' => Url::fromRoute('system.performance_settings')->toString()]);
+}

I think this message can be improved by being shorter and more explicit. Something like Flush the page cache on the <a href=":performance-page-url" title="performance settings page">Performance Settings page</a> to display the maintenance mode message to all site visitors.".

I'm not a fan of including the word "must" in this message because it sounds like something a user has to do whereas the opposite is true. It is a much rarer use-case that someone should flush the page cache. The 80%+ use-case of maintenance mode is the current behaviour. (I'm pretty sure of this because we are asking people to use maintenance mode for all core updates).

Hmmm my suggested message can be improved too :) by putting the most important bit of information first.

To display the maintenance mode message to all site visitors, flush the page cache on the <a href=":performance-page-url" title="performance settings page">Performance Settings page</a>."

#40 is more straight - changed, started to clean-up issue summary

Also I found inconsistency in how "FORM-ID" hooks documented (probably needs follow-up to normalize

I think also we need to show message about cache to messages region after save settings. It's good UI/UX for new Drupal 8 site builders.

This approach of just changing the message seems a little weird. We use maintenance mode when we don't want people using the site during updates, db backups etc... The default behavior has always been permission based access only as the current description implies. Was there an explicit decision to serve any pages whatsoever aside from the maintenance page, when in MM?

As a I think about it, why is that not a test? If a user doesn't have permission, there should only be 2 pages available, MM page, and login.

I think the bug should be fixed, and those who want an additional feature to cache pages can open up a separate feature request if they want.

:)

Adding a addition checkbox « clear the cache when in maintenance mode. Without clearing the cache visitors keep access to cached pages during maintenance mode but cannot login.  ».

The checkbox should be a settings and save it’s last state. I think it should be checked by default.

I believe that the best UX a user can have is when they can decide by themselves what to do. If you add the message below the text area, in my POV the user might just ignore that and think that it's already working as designed (the maintenance page is already showing for all users) and adds another step to the user workflow, when it can be simplyfied. So I do agree that a checkbox it's the best option here, as we give the user the ability to choose whether they want the cache to be cleared or not, and also give an easy option to choose the best option.

Therefore I'm attaching the patch that I created to add this checkbox and ability to clear cache, with the description that provides the proper explanation for the reason why this would be necessary.

#53 Applied successfully on drupal 10.1.x-dev

I think the suggestion to display a further message telling people to clear the cache form #43. I don't think adding a another checkbox here is a good one. Because a checkbox is for a state change but this is not a a state change. If you didn't want to clear the cache you set it to off press save and then it'd be set to on again. That's not how checkboxes are supposed work.

Hi, I have tested and verified the changes in MR !9015 related to the page_cache_form_system_site_maintenance_mode_alter hook and the success message after submitting the maintenance mode form. Below are the details of my verification process:

1. Verification of page_cache_form_system_site_maintenance_mode_alter Hook:

Form Field Description Update:
- Verified that the description for the maintenance mode message field now includes: "To display the maintenance mode message to all site visitors, flush the page cache on the Performance Settings page."
- Confirmed that the URL in the description correctly points to the Performance Settings page (/admin/config/development/performance).

2. Verification of Success Message After Form Submission:

After enabling maintenance mode:
- Verified that the success message reads: "To display the maintenance mode message to all site visitors, flush the page cache on the Performance Settings page."
- Confirmed that the link in the success message directs correctly to the Performance Settings page.

Cache Clearing: Cleared the site cache via Administration > Configuration > Performance to ensure visibility of the updates.

The form now correctly reflects the updated description, and the success message includes the appropriate information and link. All changes have been verified and are functioning as expected.

Attached screenshots for reference.

Before MR

After MR

Status message on form submit:

Performance settings page:

Kindly please let me know if any additional steps are needed.

Edit: Re-uploaded the missing screenshots.

Thanks!

This doesn't look right to me, I would put back to needs more info but I can see that happened years ago and it was re-opened, could definitely use UX review and there's also one technical issue in the MR.

If we really need to add a message, I would just tell people what happens rather than what to do, e.g. 'Cache pages will still be served to anonymous site visitors unless the cache is cleared' or something.

Hi, It appears that the screenshots I attached in comment #62 were either missed or accidentally deleted. To ensure that everything is in place, I am re-uploading the screenshots here.
Thanks!

Usability review

We discussed this issue at #3465362: Drupal Usability Meeting 2024-08-09. That issue will have a link to a recording of the meeting. For the record, the attendees at today's usability meeting were @AaronMcHale, @amazingrando, @benjifisher, @rkoller, @simohell, and @zetagraph.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

After some discussion we had a clear consensus on removing the description underneath the Message to display when in maintenance mode text field. Since less is more, the line adds to the visual clutter, is redundant with the status message, and most important encourages the user to do things in the wrong order. Meaning, the user might read the description while the site is not in the maintenance mode yet, follows the link, clears the cache, comes back to the maintenance page, sets the site to maintenance mode and saves the form.

In regards of the status message, there are currently two of them when a site goes into maintenance mode. First The configuration options have been saved. placed by the system module and second the newly added To display the maintenance mode message to all site visitors, flush the page cache on the Performance Settings page. placed by the page cache module.
Ideally, if technical possible, the consensus was to combine the two status messages into a single one. We had a draw and no clear consensus about the wording of the entire message. The two candidates are:

1. The site is now in maintenance mode. Cached pages will not show the maintenance mode message. To clear the cache, visit the [Performance page].
2. The site is now in maintenance mode. The maintenance mode message will not show on already cached pages. To clear the cache, visit the [Performance page].

The first sentence The site is now in maintenance mode. simply informs the user about the actual current state the site is in - the site is in maintenance mode. Which is more informative and specific than the generic information that the configuration options have been saved currently used. For the first sentence we had a clear consensus.

There was also a consensus about the third sentence To clear the cache, visit the [Performance page].. We tried to keep the wording consistent used on /admin/config/development/performance and /admin/config/development/maintenance. The performance page uses the verb clear instead of flush<code>. The concept of <code>page cache might be also too abstract and/or advanced for the person in charge, the performance page only talks about clearing cache in general and it is not necessarily important information for the status message on the maintenance page that page cache is cleared. And we've changed the link title from Performance settings page to performance page since /admin/config/development/performance is only titled performance.

The second sentence was the reason why we were drawn between suggestion 1 and 2. The thing we are trying to explain the consequences of a site being in maintenance mode. We wanted to convey that as long as there pages that were cached BEFORE the site got into maintenance mode the maintenance mode message page wont be shown to them. Cuz there could be the case that someone who is working on something while the site is maintenance mode wants that the user is still able to access the information on the page normally, while someone else wants that the maintenance mode message is directly shown and informs the user that the site is in maintenance mode instead. We are unable to know what the user's preferred choice is. But based on the information provided with suggestion 1 and 2 the user is able to make an informed decision. With the first sentence they know the site is in maintenance mode. With the second sentence they know that cached pages wont show the maintenance mode message. So based on the third sentence the user then has the knowledge to directly go to the performance page in case the person wants to ensure that the maintenance mode message is directly shown to everyone.

In case it is not possible to combine all three sentences into a single status message the recommendation would be as follows. Change The configuration options have been saved. in the system module to The site is now in maintenance mode.. And change the status message introduced with this MR from To display the maintenance mode message to all site visitors, flush the page cache on the Performance Settings page. to either:

• Cached pages will not show the maintenance mode message. To clear the cache, visit the [Performance page].
• The maintenance mode message will not show on already cached pages. To clear the cache, visit the [Performance page].

Since we had no clear consensus about the second sentence yet, we've agreed on continuing the discussion, - curious what you all think? I'll remove the needs usability review tag.

I like the second text

The site is now in maintenance mode. The maintenance mode message will not show on already cached pages. To clear the cache, visit the [Performance page].

Just one note. When i wanted to test the latest changes i ran into an issue i've already experienced on another MR. When i try to checkout the feature branch i run into the following error:

$> git checkout 2804387-maintenance-mode-enabled
error: The following untracked working tree files would be overwritten by checkout:
	core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysql/Connection.php
	core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysql/Install/Tasks.php
	core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysqlDeprecatedVersion/Connection.php
	core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysqlDeprecatedVersion/Install/Tasks.php
	core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestPgsql/Connection.php
	core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestPgsql/Install/Tasks.php
Please move or remove them before you switch branches.
Aborting

It is due to a recent commit to core https://git.drupalcode.org/project/drupal/-/commit/8b368d712d83900765744... . (DrivertestMysql changed to DriverTestMysql and DrivertestPgsql changed to DrivertestPgsql - and i am on a none case sensitive file system with macos). To fix this the issue needs a rebase. I'll set the issue back to needs work.

@rkoller I updated the fork, but have no problems with conflicts. Looks like your local git problem. Try to reset to head and discard/remove conflicting files

Thanks for the rebase. No removing these files doesn't help much, that was the initial short term fix we've tried. The only thing that properly solves the problem is a rebase. and it looks like that this error will show up for every feature branch in every MR that was created before the mentioned commit https://git.drupalcode.org/project/drupal/-/commit/8b368d712d83900765744... went in and which havent had a rebase after it went in. according to @rfay the problem is the none case sensitive macos filesystem causing the error due to the switch to camel case in the aforementioned linked commit. out of curiosity on which operating system are you @ivnish?

and thanks to your rebase i was able to git fetch the branch and then able to checkout without any issues. thanks again! and i was now able to take a look at the MR again now. The status message is now a single message, the description got removed underneath the "message to display"-field, and you have updated to one of the suggested status messages. so all the concerns we've raised in the usability meeting are covered. looks fab, thanks a lot!

i would give a +1 for RTBC, since personally i dont have a strong opinion for either of the two status message suggestions (i am fine with each of them), but i leave the status at needs review a little longer in case someone else has a strong opinion for the other. but for me this looks good to go.

I use Ubuntu 22.04

I removed the UX review task in the issue summary and added a note about it in the User interface changes section.

I added the Needs issue summary update tag for further updates to the User interface changes section to update the screenshot.

One more thing I realized is that because the message to inform the admins about maintenance mode not enabled for cached pages until the cache clear is done, is shown on form submit only, the admin might miss it and refresh or navigate away.

Therefore, it might make sense to display this message permanently till the site is in maintenance mode and every time the admin visits the /admin/config/development/maintenanceform.
Thanks!

For the issue summary mentioned in #74

updated the image in the issue summary per the suggestion in #77

Removing Needs issue summary update tag and setting status to RTBC because I think recent comments were addressed.

One month as RTBC :)

Probably shouldn't elevate issues just to get looked at.

Core committers are group of volunteers each with their own stuff going on. RTBC queue is about 115 currently so things may not immediately get merged.

@ivnish, the requirements for setting the priority for an issue are explained on Issue Priority field page of the handbook. A link to that page can also be found in the 'Issue metadata' section of each issue. Cheers.

I do not see any unanswered questions here. And the MR is implementing a solution from the UX review, #67

Updating credit

And the MR is implementing a solution from the UX review

@quietone after the review I implemented suggestions in MR (17 Aug 2024)

Two further questions on the MR.

@catch please answer

See https://www.drupal.org/about/core/policies/core-change-policies/how-to-d...

I moved the code to the page_cache module as @catch suggested

Looks good to me. Good job ivnish. Thanks!

This is only a status message. We are discussing this as a community since 9 years. This proves that we are super pedantic and lacking project management skills. Please merge this change finally.

Thanks for working on this.

I manually tested the MR since there are no tests to prove that the message is actually shown. It worked as expected. Anyway, I think we should extend the existing SiteMaintenanceTest to check if the code is working as expected and to prevent regressions in the future, especially if we are "blindly" removing original status message(s).

I also have some additional questions:

1. Aren't we worried that we could potentially remove more messages when using this code \Drupal::messenger()->deleteByType(MessengerInterface::TYPE_STATUS);? For example if there will be any custom messages included. We are not checking the actual message being removed.

2. Route system.site_maintenance_mode has permissions of administer site configuration+administer software updates, which means that if you have only administer software updates, you still have access to the maintenance mode form. But if you do not have administer site configuration permission, the newly added link to the Performance page will not work. Are we OK with keeping it there even if the user won't have access to it?

@poker10

I don't like idea to removing previous messages. As I know Drupal (and symfony) can't remove message by ID or text. But without removing we have 2 messages and messages region shows twice. Any ideas how to fix it?

I discussed this with @catch on committers Slack channel.

We both think that removing all messages without knowledge what else could be there is a bit risky. Even if the risk is small, it could affect some sites UX negatively, if any unrelated message will be removed accidentally. Another disadvantage is, what @ivnish asked in #91, that there is no way to remove just the one message, we need to change. Adding another message (and have two here) does not seems right.

I re-read the whole issue and it seems like, that the initial proposal was to add a description to the message textarea and only later it was proposed to add also a message on form submit. Based on this, the usability team proposed to remove the description and stick only with updating the submit message(s). However, the initial intention was to add only something simple like this: To display the maintenance mode message to all site visitors, flush the page cache on the Performance Settings page..

When we started mixing it with the submit message, it ended up as: The site is now in maintenance mode. The maintenance mode message will not show on already cached pages. To clear the cache, visit the Performance page.. Which is different from the original meaning, which was just to inform a user about caching. The current message also informs a user that the maintenance mode is turned on, which I think should not be in the scope of this issue, because we already have a similar message informing users about the active maintenance mode, see: https://git.drupalcode.org/project/drupal/-/blob/11.x/core/lib/Drupal/Co... (Operating in maintenance mode...). This message is intentionally excluded from the system.site_maintenance_mode route (see #184926: Incorrect message displayed when bringing a site back online). I do not think that we should add the information about the maintenance mode status back to the form, as users already see whether the checkbox is checked, or not. Or at least we should not do it in this issue.

Considering all this, I propose to return back to the original proposal - do not change submit message(s) and just add a simple and easy-to-read description to the message textarea (and do this only if page_cache module is enabled). Something like The message will not show on already cached pages without clearing the page cache.. I propose a bit different wording for the last part, so that we do not need to deal with the possible different permissions of the user (see #90.2). Another option discussed on a Slack was to put all information in the form, depending on the current state.

I am adding Needs usability review tag again and will ask for another opinion from the usability team based on these new findings.

Thanks!

Usability review

We discussed this issue at #3546438: Drupal Usability Meeting 2025-09-19. That issue will have a link to a recording of the meeting. For the record, the attendees at the usability meeting were @jannafiester, @joannajackson, @rkoller, and @simohell

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

The removal of the status message based on the rational provided in #92 sounded like a reasonable step for us if that is fixing the outlined problems including the one in #91. The change of the micro copy to the new description is ok, except it is a bit unspecific by referring only to "message"

But the way bigger problem with this change from our point of view is that the description is very very had to notice. We have skimmed through comment #92 at the beginning of the meeting and then took a look at the maintenance page on a test site with MR9015. For context two of us attended the review about one year ago only vaguely remembering the details at best, the other two looked at the issue for the very first time, so all of us looked at this issue with some fresh pairs of eyes. We've searched for an extended period of time for the introduced changes, at the end we even had two windows open, one without the MR and one with the MR, and we were still unable to notice that the description of the text field contained the change (reminded me a bit about the video of that selective attention test https://www.youtube.com/watch?v=vJG698U2Mvo). as a last resort before asking over here on the issue we've taken a look at the merge request; copied the string for the description to the clipboard and then searched on the maintenance page for that string - that way we were able to finally find the change. The reason why we haven't noticed the change was probably due to a combination of reasons; the description is at the very end of the page, it is a description for a text field, and the font size is very tiny for an important detail like that - the information has a very low information scent. If you take into consideration that sighted users usually don't read a page but skim most of the time, the odds are rather low that they will notice the information. but it might not be solely challenging for sighted users, screenreader users might also jump off early on right after the text field label "message to display when in maintenance mode" was announced. they might think "ahhh this is the field for the message displayed in maintenance mode i can jump off now". so either way, the descriptions might get missed by sighted users and/or screenreader users.

Probably in part out of scope for this issue, but our discussion shifted towards the general order of components on the maintenance page when we've tried to come up with a suggestion how to communicate the information introduced in this MR.

Currently we have, first the help text, then the checkbox to put the site into the maintenance mode, and finally the textfield. From our point of view the more logical order would be a) help text b) textfield c) checkbox , that way you consciously pass and validate the maintenance mode message before you set the site into the actual maintenance mode - currently you have to jump back and forth in regard to the reading order.

With a change of the component order the microcopy might also be rearranged. the description currently used on the checkbox is strictly speaking about the general behavior of the maintenance mode, something a help text is about, while the description introduced with this MR is about a CTA for the admin to clear the cache after the site is set into the maintenance mode.

An initial suggestion for the help text might be as follows - moving the string currently used on the checkbox into the help text:

Use maintenance mode when making major updates, particularly if the updates could disrupt visitors or the update process. Examples include upgrading, importing or exporting content, modifying a theme, modifying content types, and making backups. 
Only users with the "Use the site in maintenance mode" permission will be able to access the site. Authorized users can log in directly via the user login page. Visitors will only see the maintenance mode message. It will not show on already cached pages without clearing the page cache.

the description for the checkbox would be a more specific variant of the string currently used on text field description of this MR:

The maintenance mode message will not show on already cached pages without clearing the page cache.

The rearrangement and rephrasing of the help text is just an initial draft to convey the general idea, we haven't had enough time left during the meeting to hone the micro copy. But the basic idea was to move the description of the checkbox into the help text. The added part outlines the general behavior of the maintenance mode in regard to permissions, first about who can login and then who can view what. The last sentence of the "who can view" is sort of redundant to the description of the checkbox but that was a deliberate choice. It is an important detail and by having it be addressed twice, the odds are getting higher that the detail wont go unnoticed, after there is no proper way to highlight that detail visually more prominently aside using a status message.

How to proceed? if others agree to the general direction we've suggested, we could revisit the issue in the next meeting and do some more word smithing, in case no one else beats us to it. And talking of general direction we were also uncertain how to chop the proposed changes up, cuz the reordering of components is most likely out of the scope for this issue?

For me (and obviously others) the current solution is good enough. Let's not over engineer and wait 9 years more. I pledge for RTBC.

After reviewing this again and reading the conversation of catch and poker10 there are two approaches here. One is to follow the recommendations of the Usability team, which includes some out of scope ideas, and the other is to add description text to the maintenance mode text field. I lean strongly to respecting the expertise of the Usability team and to stay in scope. So, I would prefer to change the description text to what is recommended in #96 and in a follow up issue explore the other points in #96.

Given #96 and #98 this issue needs work. I think the suggestion in #98 to change the description to the suggested text in this issue and file a follow-up to address the rest makes sense to me.

I applied suggestions from #96.

thanks you for the updates. i've pulled the latest changes but when i try to clear caches with drush i run into a fatal php error:

PHP Fatal error: Uncaught Error: Class "Doctrine\Common\Annotations\TokenParser" not found in /var/www/html/repos/drupal/core/lib/Drupal/Component/Annotation/Doctrine/StaticReflectionParser.php:192

the issue probably needs another rebase due to recent changes in 11.x (#3550917: doctrine/annotations is abandoned)

I rebased the MR. All tests passed.

Suggestion : Divide as per the intent of text, to make it more scalable to eyes. Example below.
https://www.figma.com/design/yxXkBgG8uvgxHJFWLwnuGC/Drupal.org?node-id=7...

Usability review

We discussed this issue at #3557881: Drupal Usability Meeting 2025-11-21. That issue has a link to a recording of the meeting. I am giving issue credit here to the attendees: @anmolgoyal74, @benjifisher, @pallavi singh3013, @rkoller, @sahilps6, @simohell, and @the_g_bomb.

@ivnish, thanks for the updates since the last review (Comment #96). We looked at the results, and we recommend making three tweaks:

1. Start a new paragraph with "Only users ..." instead of using a <br> tag.
2. Make "permission" a link to /admin/people/permissions/module/system (permissions for the system module) instead of the generic permissions form. (The route is user.admin_permissions.module with the parameter modules => system.)
3. Change "Visitors" to "Other visitors". (This sentence used to be the start of the help text. Now that it is in a paragraph after two sentences that mention authorized users, it makes sense to exclude them explicitly.)

In addition to those recommendations, we have a suggestion (already mentioned in Comment #103). We think it will make the two paragraphs of help text easier to scan if we add a header to each paragraph. If you take this suggestion, then I guess the headers should use <h2> elements to preserve the page hierarchy. So the text would look something like this:

When to use maintenance mode

Use maintenance mode when making major updates, ...

Access during maintenance mode

Only users with the "Use the site in maintenance mode" permission ...

I am adding the tag for an issue summary update. Under "User interface changes", we should have an updated "after" screenshot. Since this issue rearranges the text, it will be helpful to add a "before" screenshot as well.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

Another point that was raised in the 2025-11-21 usability meeting is that the current approach informs the user about caching. Looking at the comments, there are some suggestions to recommend clearing caches. We like the current approach (informing without making a call to action). Depending on how the site is used, it might be a good thing to let most visitors see the cached content instead of the maintenance message.