Provide a method dedicated to setting the default revision

Problem/Motivation

Way back in 2012 we added support for declaring revisions as the current revision: #218755: Support revisions in different states. This has been implemented with a getter and setter all rolled in the same method:

  /**
   * Checks if this entity is the default revision.
   *
   * @param bool $new_value
   *   (optional) A Boolean to (re)set the isDefaultRevision flag.
   *
   * @return bool
   *   TRUE if the entity is the default revision, FALSE otherwise. If
   *   $new_value was passed, the previous value is returned.
   */
  public function isDefaultRevision($new_value = NULL);

This is contrary to how we do things nowadays, the rest of core always uses dedicated getters and setters. This is confusing, and for people unfamiliar with the interface it is difficult to discover how a default revision can be set.

The confusion is made worse because in the example implementation in NodeRevisionsTest it appears that we are supposed to set the isDefaultRevision property directly, which is a WTF since this is a protected property. The below code only works because the write call that sets the isDefaultRevision property is intercepted by the magic __set() method in ContentEntityBase.

    // Make a new revision and set it to not be default.
    // This will create a new revision that is not "front facing".
    $new_node_revision = clone $node;
    $new_body = $this->randomMachineName();
    $new_node_revision->body->value = $new_body;
    // Save this as a non-default revision.
    $new_node_revision->setNewRevision();
    $new_node_revision->isDefaultRevision = FALSE; // Setting a protected property directly??!?
    $new_node_revision->save();

Proposed resolution

1. Solve the WTF and improve discoverability by providing a setDefaultRevision() method on RevisionableInterface.
2. Deprecate the setting functionality of isDefaultRevision().
3. Update all existing code that calls isDefaultRevision() with the goal of setting the property to use setDefaultRevision() instead so this can serve as examples to developers.
4. Replace existing code that sets the isDefaultRevision property through the magic setter to use setDefaultRevision() instead.

This probably doesn't require any new test coverage, this will be adequately tested by adapting the existing tests.

Remaining tasks

Implement.

User interface changes

None.

API changes

A new method setDefaultRevision() added to RevisionableInterface.

Data model changes

None.