[policy, docs] Use post updates for empty 'clear the cache' updates

+1 makes sense to me.

I'm confused by this -- isn't the empty update hook entirely to make sure that the site builder gets the message that they need to visit update.php when the applicable release is installed and thereby trigger a cache clear? It's for the situation where you haven't known to run update.php. If you did run update.php, the caches were cleared anyway. So I am not sure how post updates address the need.

@xjm post updates are listed on updates.php too and you need to run update.php to run it. If there's only post updates to run hopefully you still have the message that there are updates to run - if not we have a bug.

+1 for sure. Post updates are kinda even designed around the idea to be cache-clearable at any point without issues, unlike normal updates, where the cache clear can just happen afterwards.

post_update functions are executed after the normal updates, but in the same batch process, which means that each message which is shown on normal updates also apply to post updates.

I've just tested adding a new function to views.post_update.php and the warning shows on the status report so we're all good here.

I think we should move this views hook_update_N so to avoid any potential update numbering issues for as long as possible.

@catch well we made it yesterday - so there won't be many and we've already used the 8006 update number so we shouldn't use that either. I don;t like hook_update_N - very tricky to tie down with multiple branches :(

#2796953: [regression] Plugins extending from classes of uninstalled modules lead to fatal error during discovery added an empty system_update_8201(). Do we want to reroll #8 to convert that one too?

#8 no longer makes sense, because of the reason pointed out in #9, but the mitigating circumstances in #10 certainly no longer apply.

We simply need to make this issue the new policy for any of those "empty cache clear" update functions going forward, starting with 8.3.

Retitling accordingly.

Let's do this and make it an official policy. Empty update hooks are really bugging me. :/

I'm concerned that people won't know about this policy if we still have empty update hooks in our codebase documented as being there to clear the cache.

What about creating a patch as part of this issue to change the comments within all of our existing empty update hooks? Similar to what we have in block_content_update_8002()?

+1 to want @effulgentsia says... lets create a child issue to add such a comment to all hook_update_N implementations that exist to clear caches.

+1 for this policy based on the above. I think we need to document it on the API docs for those hooks, though.

+1 to want @effulgentsia says... lets create a child issue to add such a comment to all hook_update_N implementations that exist to clear caches.

+1. I think we can do that in a followup once we update the hook documentation (but create the followup before commit).

This came up again in #2851736-42: Language reference fields do not implement OptionsProviderInterface so created a change notice https://www.drupal.org/node/2960601 and follow up issue #2960605: Add docs to the empty hook_update_N used for cache clearing.
I suggested we should add the following docs to all empty cache clearing hook_update_N.

// Use of hook_post_update_NAME instead to clear the cache. 
// The use of hook_update_N to clear the cache has been deprecated
// see https://www.drupal.org/node/2960601 for more details.

Please feel free to adjust the change notice and above docs in the follow-up issue.

All the feedback has been addressed so back to RTBC.

but create the followup before commit

What commit? :D

Thinking about this for a bit ... couldn't there be hook_post_update_N updates relying on a valid system? Let's for example think about config schema being changed. In this case we should be able to do a $config->save() with validation in hook_post_update_N

"Needs review" for #25. Anyone else have thoughts on that?

As per \Drupal\system\Controller\DbUpdateController::triggerBatch.

    if ($post_updates) {
      // Now we rebuild all caches and after that execute the hook_post_update()
      // functions.
      $operations[] = ['drupal_flush_all_caches', []];
      foreach ($post_updates as $function) {
        $operations[] = ['update_invoke_post_update', [$function]];
      }
    }

We only clear cache before post update hooks execution so this mean when we execute the post update hook the schema changes are already part of the system.

Thanks for finding that! Back to Fixed.

We also clear the caches again after post updates in \Drupal\system\Controller\DbUpdateController::batchFinished(). So we do clear the cache even if there are no post updates :)