Mark Content Moderation module as stable

Let's also fix the module description while we're here :)

...not anymore. :)

Compared the CSS in #13 to HEAD, only one change since then. Updating.

Thanks

@plach pointed out that I should review the frontend code being marked as stable. I'm not sure what is the workflow for fixing these (maybe you want to open separate issue for that) but here's the feedback that I have:

1. +++ b/core/themes/stable/css/content_moderation/content_moderation.module.css
   @@ -0,0 +1,42 @@
   +ul.entity-moderation-form {
   

   We should remove the element type from all of the selectors. It messes up the selector specificity and makes refactoring more difficult.

2. +++ b/core/themes/stable/css/content_moderation/content_moderation.module.css
   @@ -0,0 +1,42 @@
   +ul.entity-moderation-form li {
   

   Could we add a class according to the BEM standard for the li elements so we wouldn't have to nest the selector? Something like entity-moderation-form__list-item.

3. +++ b/core/themes/stable/css/content_moderation/content_moderation.module.css
   @@ -0,0 +1,42 @@
   +ul.entity-moderation-form .btn {
   

   What is the .btn for? I couldn't find any instances of this class in core.

1. Done.
2. I've opted for "entity-moderation-form__item", sounds natural to be an "item" in an "entity-moderation-form" more than a "list item" and it kind of ties in with point 1, being agnostic of the HTML elements used.
3. This looks unused to me too. Removing.

Attaching screenshots before and after refactor. Appearance seems unchanged.

The changes to the CSS looks good 🤩Thank you! I'm fine from my frontend perspective with this being marked as stable.

This is really exciting!

The one concern I have is that the help documentation is a bit thin, both in hook_help() and on https://www.drupal.org/docs/8/core/modules/content-moderation/overview. I think we need to do a bit of work to pass the documentation gate.

Here's a patch with some updates to hook_help... not expecting this to get it over the line but figured we could start here.

I've also made some (minor) changes to the doco pages for clarity, but I wasn't entirely sure what sections needed more information as the page is quite detailed. If anyone has input on what areas aren't sufficiently covered, let me know and I can give it a go.

+++ b/core/modules/content_moderation/content_moderation.module
@@ -34,13 +34,13 @@ function content_moderation_help($route_name, RouteMatchInterface $route_match)
+      $output .= '<p>' . t('The Content Moderation module allows you to expand on the default "unpublished" and "published" states for content. It allows you to have a published version that is live, but have a separate working copy that is undergoing review before it is published. This is achieved by using <a href=":workflows">Workflows</a> to apply different states and transitions to entities as needed. For more information, see the <a href=":content_moderation">online documentation for the Content Moderation module</a>.', [':content_moderation' => 'https://www.drupal.org/documentation/modules/content_moderation', ':workflows' => '/admin/help/workflows']) . '</p>';

Hardcoding /admin/help/workflows is not going to work for sites installed in a subdirectory of a domain.

You'll want to change this to Url::fromRoute('help.page', ['name' => 'workflows'])->toString().

I think it'd be good if e.g. @webchick could take a look at the updated hook_help() in #27 and the updated docs at https://www.drupal.org/docs/8/core/modules/content-moderation/overview.

Adding @esod to the credit list (as well as saving credit for reviewers). Thanks for working on this!

Having Content Moderation as a stable feature for D8.5 would be amazing, so very happy to do final review and sign-off on this once the documentation changes are ready for review! Feel free to pester me mercilessly once this gets to RTBC. :D

@webchick: docs have been updated, but I don't know what extent of docs changes is expected/was discussed.

Updated patch based on #30, but, being a non-dev I couldn't work out Url::fromRoute() so I copied the approach from block.module and it seems to work. If this is not OK, I can still update the patch but would need specific instructions (or for someone else to do it right!).

In terms of the current status of the docs: I think https://www.drupal.org/docs/8/core/modules/content-moderation/overview is in a good place. It may seem a bit light but it's tricky to write pure doco for Content Moderation because it relies quite heavily on Workflows and I don't think it makes sense to duplicate what's in that doco - which is quite comprehensive IMO. So the page provides a thorough summary of how it works, via an example configuration with screenshots (someone else did this before I got involved so thanks to whoever that was).

The hook_help changes just beefed up and clarified what was there, but again are pretty light because as soon as you start to get into detail, you are documenting Workflows - not Content Moderation.

+++ b/core/modules/content_moderation/content_moderation.module
@@ -32,15 +32,16 @@ function content_moderation_help($route_name, RouteMatchInterface $route_match)
+      $workflows = \Drupal::moduleHandler()->moduleExists('workflows') ? \Drupal::url('help.page', ['name' => 'workflows']) : '#';

Doesn't content_moderation depend on workflows? That'd mean that module exists check would always succeed!

Wow, the docs at https://www.drupal.org/docs/8/core/modules/content-moderation/overview are stupendous, and way above and beyond what we require for the documentation gate. Annotated screenshots, a step-by-step scenario walkthrough (including easy-to-miss things like permissions), cross-links to https://www.drupal.org/docs/8/core/modules/workflows/overview where appropriate, etc. Great work!

Is there a reason these handbook docs (and the Workflows ones, for that matter) are still tagged as "Incomplete"? At a glance, it seems to cover everything that Content Moderation does, I guess with the exception of reviewing changes for approval, since the View for that just went in like a few days ago.

As far as hook_help() goes, the standards for that are at https://www.drupal.org/node/632280. "Uses" should centre around what admin pages the module itself exposes, so is probably fine to leave permissions out, since that applies to all modules.

I would probably recommend just copying directly from https://www.drupal.org/docs/8/core/modules/content-moderation/overview where possible vs. maintaining two sets of documentation, and shorten things up quite a bit since the handbook documentation is so comprehensive.

So maybe something like:

---

<h3>About</h3>

<p>The Content Moderation module allows you to expand on Drupal's "unpublished" and "published" states for content. It allows you to have a published version that is live, but have a separate working copy that is undergoing review before it is published. This is achieved by using <a href=":workflows">Workflows</a> to apply different states and transitions to entities as needed. For more information, see the <a href=":content_moderation">online documentation for the Content Moderation module</a>.</p>

<h3>Uses</h3>

<dl>
<dt>Applying workflows</dt>
<dd>Content Moderation allows you to apply <a href=":workflows">Workflows</a> to content, custom blocks, and other <a href=":content_entities">content entities</a>, to provide more fine-grained publishing options. For example, a Basic page might have states such as Draft and Published, with allowed transitions such as Draft to Published (making the current revision "live"), and Published to Draft (making a new draft revision of published content).</dd>
<dt>Moderating content</dt>
<dd>You can view a list of content awaiting moderation on the <a href=":moderated">moderated content page</a>. This will show any content in an unpublished state, such as Draft or Archived, to help surface content that requires more work from content editors.</dd>
</dl>
</dl>

---

I was going to harp on some of the overly technical language here (e.g. "content entities") but then noticed the sample help page provided by the documentation team at https://www.drupal.org/node/632280 does the same thing.

Also confirmed that #37 is correct; Content Moderation requires Workflows so it's always gonna be there, so we can simplify this further by removing the special logic.

+++ b/core/modules/content_moderation/content_moderation.module
@@ -34,13 +35,20 @@ function content_moderation_help($route_name, RouteMatchInterface $route_match)
+        $output .= '<dd>' . t('You can view a list of content awaiting moderation on the <a href=":moderated">moderated content page</a>. This will show any content in an unpublished state, such as Draft or Archived, to help surface content that requires more work from content editors.', [
+            ':moderated' => Url::fromRoute('view.moderated_content.moderated_content')
+              ->toString()
+          ]) . '</dd>';

Supernit: there's some weird indentation going on here, the last 3 quoted lines are indented by two spaces too many. But … that's not enough to block RTBC!

Less of a nit: this URL will only actually work if that view (which is optional default config) is not disabled or even deleted by the user. If it isn't, this will yield a RouteNotFoundException. This unfortunately is enough to block RTBC.

WFM!

#46 only failed because HEAD is broken. This looks ready! :)

(I reran tests.)

Awesome work on the handbook documentation.

One thing though. I think in addition to the CSS, this should also be copying the relevant template into stable?

Good point, let's do that :)

One thing though. I think in addition to the CSS, this should also be copying the relevant template into stable?

Can we get a follow up for a test for this, we have one for the CSS files already, we should for templates too

Added #2939988: Remove content moderation exclusion from StableLibraryOverrideTest for #53.

Updating credit.

🎉

🎉 Awesome! Congrats everyone.

Congrats folks, awesome work!

Thanks folks, congrats. I'll update the project page for wbm

📣

I've updated the docs pages to remove the Incomplete status based on #2897132-38: Mark Content Moderation module as stable.

https://www.drupal.org/docs/8/core/modules/content-moderation/overview
https://www.drupal.org/docs/8/core/modules/workflows/overview

Despite this thread, the Experimental modules in Drupal 8 page, and the WI: Content Moderation module roadmap thread, it's still hard for end-users to determine if Content Moderation is stable or still experimental in the 8.4.5 core release. For anyone who might be looking for this information I can confirm that it is still experimental.