Explore splitting entity type definitions into two storage/non-storage related definitions

The DX of installing/updating keys on the entity definition isn't ideal if you aren't making schema changes. It feels a bit redundant to write an update hook to replace keys in a data structure you've just adjusted in an annotation.

While I understand the frustration, I also think that it is safer to always write an update. It is also easier to always have an update, event it has no effect instead of having to think about the use cases when an update is required and when not.

+1 to this. We hit this with field_encrypt - see #3153125: Cache issue persists after update to 8.x-2.0-alpha2

The current docs for for hook_entity_type_alter() feel very insufficient...

/**
 * Alter the entity type definitions.
 *
 * Modules may implement this hook to alter the information that defines an
 * entity type. All properties that are available in
 * \Drupal\Core\Entity\Annotation\EntityType and all the ones additionally
 * provided by modules can be altered here.
 *
 * Do not use this hook to add information to entity types, unless one of the
 * following is true:
 * - You are filling in default values.
 * - You need to dynamically add information only in certain circumstances.
 * - Your hook needs to run after hook_entity_type_build() implementations.
 * Use hook_entity_type_build() instead in all other cases.
 *
 * @param \Drupal\Core\Entity\EntityTypeInterface[] $entity_types
 *   An associative array of all entity type definitions, keyed by the entity
 *   type name. Passed by reference.
 *
 * @see \Drupal\Core\Entity\Entity
 * @see \Drupal\Core\Entity\EntityTypeInterface
 */
function hook_entity_type_alter(array &$entity_types) {
  /** @var $entity_types \Drupal\Core\Entity\EntityTypeInterface[] */
  // Set the controller class for nodes to an alternate implementation of the
  // Drupal\Core\Entity\EntityStorageInterface interface.
  $entity_types['node']->setStorageClass('Drupal\mymodule\MyCustomNodeStorage');
}

In 8.7.0 the

You need to dynamically add information only in certain circumstances.

changed quite drastically. There are now many situations where this does not work. I'm not sure even the example in the hook works now.

I'm not sure even the example in the hook works now.

It doesn't, you need to update the last installed definition and set the new storage class there as well :/