Problem/Motivation
Nodes - as the canonical example of revisionable entities - store the revision author, the revision timestamp and a log message for each revision. The Node entity declares these fields in its baseFieldDefinitions().
Custom blocks only provide a log, but no revision author or timestamp.
We should make this consistent and make it easy for contrib entity types to provide the same behavior.
#2666808: Add a revisionable entity base class and log interface introduced three revision metadata fields, which are named "revision_created, revision_user, revision_log_message". However the core still assumes at some places that they are called "revision_timestamp, revision_uid, revision_log". That is the case where the node entity and the block entity use the previous nomenclature. But unfortunately this is not the only place.. There is one another really important place and it is in SqlContentEntityStorage::getTableMapping where only the old nomenclature is used to put these revision metadata fields in the "entity_type_id_revision" table. #2666808: Add a revisionable entity base class and log interface did not extend the list with the new revision metadata fields and what now happens is that if you use the new RevisionLogEntityTrait your revision metadata fields will not be put - as they should - in the "entity_type_id_revision" table, but they will be put in the field table.
Proposed resolution
Provide a revision_metadata_keys key in the entity annotation which provides a mapping of common identifiers like "log", "uid", "created" to the actual field names. Because there are places where we need the list of revision metadata fields explicitly, for example in SqlContentEntityStorage::getTableMapping() or in ContentEntityBase::hasTranslationChanges() with #2615016: [PP-1] ContentEntityBase::hasTranslationChanges doesn't skip the revision metadata fields leading to wrong result, this is not part of the entity_keys key, even though it is similar in nature. This also allows us to ignore (at least for the scope of this issue) the fact that entity key fields get a NOT NULL constraint in the SQL schema. Note that calling EntityType::getKeys() will also not return the revision metadata keys.
In order to provide backwards-compatibility, in the case that revision_metadata_keys is not set, we will check the field definitions if fields with the appropriate names (revision_log, revision_log_message) exist and use those as as values. This behavior can be disabled by a boolean parameter which is utilized in RevisionLogEntityTrait because due to the above checking of the field definitions, checking the revision metadata keys while building the field definitions would lead to infinite recursion.
Because the hardcoding of incorrect revision metadata field names in SqlContentEntityStorage::getTableMapping() entity types using RevisionLogTrait have the database columns for the revision metadata fields in the wrong table. (They are in the revision data table, but they should be in the revision table.) To correct this, an update function is provided that moves the field values to the correct table and fixed any views that reference the old table names in their views field configuration.
Remaining tasks
Follow-up issue for D9 to remove the hard coded revision metadata field list from \Drupal\Core\Entity\RevisionLogEntityTrait::getRevisionMetadataKey and RevisionLogEntityTrait should create the fields only if they are mentioned in the entity annotation.
Follow-up issue for D9 to remove the backwards compatibility parameter from \Drupal\Core\Entity\ContentEntityTypeInterface::getRevisionMetadataKeys and make the annotation for revision metadata keys obligatory for revisionable entities.
User interface changes
API changes
New functions :
-EntityTypeInterface::getRevisionMetadataKeys
-EntityTypeInterface::getRevisionMetadataKey
-EntityTypeInterface::hasRevisionMetadataKey