[META] Plan for Workbench Moderation release 7.x-2.0

Hi Thomas,

Thanks for asking about this hear an in IRC. I'm sorry I didn't have time to respond a couple of days ago. 2.x is slowly moving forward, driven primarily by Robeano and me. Here are the big differences between 1.x and 2.x.

Workflows built on CTools exportables.

In 2.x the draft, needs_review, and published states are all exportable objects the same way mini panels, custom access rulesets and other CTools Export UI driven objects are exportable. This is accomplished with a submodule within Workbench Moderation 2.x called Workbench Workflows. The UX here could use a lot of attention and help text. It's a UI directly copied from other Export UI modules like Mini Panels. The big idea behind using Export UI (aside from the exportability) is that Export UI makes complex access rules much easier. With 1.x we got a lot of requests to vary workflows or access to states within a workflow by Organic Group, node ownership, arbitrary field values within a node, and a bunch of other things. CTools access plugins had already answer that space pretty well so we’re just using what was already available. There’s room to make the UI much more tailored to this use case.

Reliance on State Machine 3.x

The other big change in Workbench Moderation 2.x is that almost everything has moved to State Machine (3.x). State Machine and Workbench Moderation are both modules that allow for “forward revisions.” The code to make this possible in D7 is complex and messy. Luckily, that part will be much easier in D8. The maintainers of State Machine focused on getting State Machine to a full release (2.0) while Robin and I did more drastic changes in a 3.x branch. Those changes include:

• Splitting out the class files
  State Machine is built around a base class that has no Drupal awareness and a subclass for the node implementation. The 3.x branch inserts a middle class with no node assumptions. The idea here is that additional classes could be written for users, terms and other entity types. We won’t know the success of this approach until we have implementations beyond the node implementation.
• Renaming some database tables
  For an entity-type-agnostic approach we didn’t want database tables starting with “node_”
• State change records as entities themselves.
  In Workbench Moderation and State Machine (and other similar modules) there are tables that track when nodes move from Draft to Needs Review to any other state. We’ve gotten requests to attach more data to that record specifically. For instance a log message or a user reference for an “assignee” field. These fields don’t belong on the node. They belong with the change from Draft to Needs Review. So we made the “State Flow History Record” be an entity itself.
• Test coverage
  We’ve put in a lot more test into State Machine 3.x.

What still needs to be done

• Documentation
  Here are two issues for implementations of hook_help() in Workbench Moderation #1866258: Add implementation of hook_help and State Machine #1866256: Add implementation of hook_help.
• Upgrade Path
  There is not yet an upgrade path from 1.x to 2.x
• Views integration
  In Workbench Moderation 1.x the moderate tab is a hard-coded interface that combines records of each revision with the state changes each transition went through. Workbench Moderation 2.x currently breaks that out into two tabs that are just Views: one tab for that has a row per revision and another tab that has a row per state change. This is a place where some major UX work could go. We’d like this interface to be Views-driven. However the two tab approach is not very good. Every Palantir.net client using 2.x has had completely customized Views and I’m not sure what the stuff View should be. Part of the difficult here is a broken “published” handler. This handler checks if a revision is both in the node table and has a status of 1. #1775540: Additional fields joins break with the latest version of Views
• Node edit form
  UX work would also benefit the node edit page. State Machine 3.x is putting it’s alterations of the node form within the Revisions vertical tab which creates some confusion with the “Publishing Options” vertical tab.

I'm sure some of this needs more clarification. If you don't have any objection, I'd like to move this text to the issue summary and treat this as a META issue for tracking other tickets.

stevector, big thanks for the description! I need the workbench for entities (commerce product and order), so I successfull install Workbench Moderation 2.x from git (it was not so easy to find this version in git, why you didn't release dev version on module page?).
It works normally for node edit form, but I can't understand how to add it for entities?

Can you please post some examples or howto for add states to entities for commerce module, entity api or other?

And it is too hard to understand, what I must select in the Context page of workflow? I see many link fields from nodes and can't understand what I must select. Can I select nothing?

Hi Murz,

Thanks for testing! We don't yet have an implementation for an entity type beyond nodes, just an architecture that should support additional entity types. If you want to write one for Commerce entities, I could give you some guidance.

We don't yet have a dev release posted on the project page because as you saw there are still some major UX rough spots. For the Context page of workflow, you don't have to select anything. That screen is helpful if you need to make workflow restrictions based on a related Context. For instance, in one implementation I needed a relationship to the Organic Group that the node was in so that workflow access could be restricted accordingly. This is one of the places we could use UX work. Right now that interface is copied right out of mini panels.

As I test on my site, it already can be used for node workbench, so if you release dev version, you got more testers and feedback, and maybe useful patches. Because now is not so easy to see that new version is in active development.

About commerce entities - will be very good if you can help me to add workbench for it, because I must do something for storing commerce product states, with your module or with my separate code, so your help will be awesome! Can you post some example articles on drupal.org site (for public access), or mail me to murznn at gmail.com?
At first, I need to add states draft-review-published for commerce_product entity.

Now that we can indicate an issue's parent issue, perhaps all remaining blockers for the 2.0 release could have this issue listed as the parent? That way we'd know what's needed and could potentially help?

I'm still working on the 2.x branch. However the work is stalled due work overload by other stuff.
I've added related issues I've been working on the make the branch usable / better integrated in other modules.

Added the upgrade path one.

After I commit 1.x RTBCs, I'm setting the version to 7.x-2.x. So you find the issues that require forward porting there.

Checked all of them - one was a "feature request" added it. All others were unrelated since the 2.x branch uses State Machine / State Flow for the affected operations.

@das-peter: There are more coming. As I'm not sure which are unrelated, feel free to mark them as fixed after I send them over to you. Going forward let me know if I can mark all bugs as fixed, assuming that you only want new features in that queue (which I'll send over).

Can we make sure not running into feature regressions if we not always go from top (2.x) down (1.x)?

@hass I think this would be quite hard because the totally different approaches of the two branches. If a feature bases on the revisioning handling we would have to implement it totally different even in different non-project modules.
I don't think we can achieve feature parity here. I even thought about forking the 2.x branch into an own project e.g. Workbench State Machine.

If 2.x has more features I'm fine, but it need to support all what 1.x supports. Otherwise - how should people upgrade? I expect a smooth upgrade where update hooks bring me to 2.x. No export/import or manual programming. The module code need to handle all. If a feature goes away or is going to be replaced by a better feature that take over the previous stuff I'm fine. Don't get me wrong... If there is a minor thing nobody really need we could be fine, too. I just fear that 1.x user see the new 2.x and do not understand anything... I cannot train all of them again. If usability is a lot better aka totally intuitive I'm fine, too. We had lot of usability difficulties with people using it. Some issues have been bugs, but there are still a lot of newbies who are not familiar with software at all and seriously failed with workbench 1.x