$workflow param is no longer required in getInitialState

+++ b/core/modules/workflows/src/Plugin/WorkflowTypeBase.php
@@ -117,7 +117,7 @@ public function onDependencyRemoval(array $dependencies) {
-  public function getInitialState(WorkflowInterface $workflow) {
+  public function getInitialState() {

+++ b/core/modules/workflows/src/WorkflowTypeInterface.php
@@ -80,13 +80,10 @@ public function workflowStateHasData(WorkflowInterface $workflow, StateInterface
-  public function getInitialState(WorkflowInterface $workflow);
+  public function getInitialState();

This is the API change.

Is this WI Critical?

+++ b/core/modules/content_moderation/src/Plugin/WorkflowType/ContentModeration.php
@@ -340,11 +340,11 @@ public function getConfiguration() {
-  public function getInitialState(WorkflowInterface $workflow, $entity = NULL) {
+  public function getInitialState($entity = NULL) {

If it's optional, then how can you ensure it is passed?

Shouldn't $entity be required?

#5: Thanks for that explanation! That's then something we should document in both Workflows' API docs ("is not tied to entities") and Content Moderation's docs ("is tied to content entities").

Adding some inline docs to \Drupal\content_moderation\Plugin\WorkflowType\ContentModeration::getInitialState to explain why we are passing in $entity and what we're doing with it.

This should be ready for RTBC now, the code from @Sam152 looks perfect to me, this would be a nice parameter to remove.

1. The comments added in #8 are very helpful, thanks! I think it'd be good to add though that all calls made to getInitialState() by the Content Moderation module's code MUST pass the $entity parameter.
2. I still think some documentation like #5 would be great to have in workflows.api.php and content_moderation.api.php.
3. However, here's a key question: What is a use case of a non-entity workflow?. In other words: why not make getInitialState(EntityInterface $entity) the actual API? Then we don't need to deal with any of these ambiguities. In other words, I'm questioning Currently $entity is not part of the workflows interface because we can't assume all workflow types are necessarily going to be concerned with entities at all

Since Drupal's all about entities, I think it's reasonable to limit to entities. That's also what https://www.drupal.org/project/jsonapi did, which allowed it to become significantly simpler (the benefit/impact here is much smaller obviously, we're talking about a single API method).

However, it seems you're strongly convinced that there are use cases beyond entities :) I respect your opinion as the module maintainer of course. I'm merely trying to help you make your maintainer life as simple as possible!

Happy to add the other suggested docs. Is that in scope for this issue?

I think it is, because the lack of clarity around this is the entire reason this issue was spawned!

We could throw an exception and/or trigger_error if $entity is not set?

I would not want to make $entity a required field in Workflows without passing it by @alexpott who lead the work on splitting it out of Content Moderation. If we are making workflows entity specific we might as well merge the two modules back together.

See, I didn't know about that background/history! :)

My key concern is that some people end up interacting with Workflows' API, and expect it to work also for Content Moderation. But the Workflows API specifies you don't need to pass $entity to getInitialState(). So this is confusing/somewhat contradicting.

But it sounds like this was already discussed. Which issues should I read to understand how we arrived at the current architecture?

Workflows was introduced in #2779647: Add a workflow component, ui module, and implement it in content moderation.
The $entity param was added to getInitialState() in #2817835: When enabling moderation apply a relative state.

Adding the two api.php files, and throwing an exception if the $entity in getInitialState() is not an instance of ContentEntityInterface.

1. +++ b/core/modules/content_moderation/src/Plugin/WorkflowType/ContentModeration.php
   @@ -345,6 +346,9 @@ public function getInitialState($entity = NULL) {
   +    if (!($entity instanceof ContentEntityInterface)) {
   +      throw new \InvalidArgumentException('A content entity object must be supplied.');
   +    }
   

   +1

2. +++ b/core/modules/workflows/workflows.api.php
   @@ -0,0 +1,17 @@
   + * This allows the module to tailor the workflow to it's specific need. For
   + * example, Content Moderation module uses it's the Workflow Type Plugin to
   

   s/it's/its/

3. +++ b/core/modules/workflows/workflows.api.php
   @@ -0,0 +1,17 @@
   + * link workflows to entities. On their own workflows are a stand alone concept,
   

   s/own/own,/
   s/stand alone/stand-alone/

Fixed these nits (and a few more), and RTBC'd!

Rerolled :)

Looks like this was committed to 8.5.x but the issue was not updated: http://cgit.drupalcode.org/drupal/commit/?id=d4165ff1085da979f52b23a9d8f...

D'oh, right.

But that's only been committed to 8.5.x anyway, we still need this to be committed to 8.4.x. So actually the state of this issue is still accurate :)

Nope, I'm wrong — it's since been cherry-picked: http://cgit.drupalcode.org/drupal/commit/?id=7da23b0bbf0a55dd54fc7a352f9... — hurray!

This still needs a change record though.

I don't think it makes sense to add this change to the existing https://www.drupal.org/node/2897706 change record, since it's independent from that change set.

Published the CR