Clarify and document wording around drafts, revisions, published & friends

Some points for discussion. I'm not sure these are good ideas, but some current thinking based on constantly getting turned around by terminology around this for approaching ten years now. Also we're inconsistent with these terms when discussing things amongst ourselves as core developers, let alone in UI text, so while we should think about interface text, we should also think about a shared conceptual vocabulary for code comments and issue discussions as well.

I think we should completely excise 'forward revision' from our vocabulary. Depending on what kinds of workflow modules people are using, draft/pending revisions can be in the past relative to what is currently published, this is especially true with workspaces. The timestamp on a revision is not important for us really.

Draft revision vs. default revision gets a bit tricky too. i.e. some revisions are draft, but might be rejected drafts that remain in the history but are archived rather than waiting to be published. Also a draft revision of an unpublished node could also be the 'default revision' - you can edit an unpublished node and create new revisions while doing so, but the distinction between default and draft isn't necessary when nothing is published.

This leads me towards 'pending revision' as in 'a revision that has not been published yet, in some kind of active workflow state'.

In turn, using pending revision, allows 'draft' and 'draft revision' to refer to revisions of not-yet-published entities as well as not-yet-published revisions to published entities, both of which are valid from a common sense perspective at least.

Published revision means 'the default revision on a published entity'. 'default revision' means 'the revision you get when you load the entity without requesting anything specific'. These are two slightly different concepts and I think content authors really care about published vs. draft versions and not defaults.

6. An entity as a whole can be in a draft state in the sense of the default revision being unpublished, but this is absolutely not a 'forward revision' in that case.

7. The concept of 'default revision' as such is a technical implementation detail and not really relevant to content authors. People really need to know - are they editing the published version or a draft?

In terms of UI text:

"There is a published version of this $entity/bundle, you are currently editing a draft version"

"The version you are editing is a draft, and must be published for changes to appear on the site"

"This change can not be made to drafts and must be done after the $entity/bundle is published"

Something like that...

Opened a follow up about changing 'forward revision' to 'draft revision' #2890364: Replace all uses of "forward revision" with "pending revision".

Big +1 on #2 FWIW

This is marked as MUST-HAVE in the roadmap.

#1643354: [Policy, No patch] Overhaul the entity revision terminology in UI text really has a lot of useful discussion around this (and some stalled discussion as well), with a survey of terminology used in various other places. Here are some examples from other sources from that issue (circa 2012, but there you go):

I think #2890364: Replace all uses of "forward revision" with "pending revision" was meant to illustrate where that proposed terminology would and wouldn't work. We can look at examples from that patch

From #2890364: Replace all uses of "forward revision" with "pending revision":

If #2875154: Clarify and document wording around drafts, revisions, published & friends is still so early in discussion, how do we know if this is RTBC? I see Bojhan in #15 saying it is signed off. However, let's consider the implications for a bit. With the terminology on this issue, you can have a non-draft revision that is a draft ;) That is, you have an unpublished default revision (AKA draft) yet you don't have any draft revisions (AKA forward revisions).

@Bojhan asked for clarification on #17. His point was that the user does not necessarily need to get different terminology based on whether the draft has a prior published variant or not. That is a good point. So my point in #17 may be moot. However, we realized another thing in the meantime...

Draft is a workflow state included in core (alongside Archived and Published). Let's say I also add a state "Approved for translation (before publication)" which is not yet published but is more reviewed than Draft (goes between Draft and Published). Now I can have a forward revision that is "Approved for translation (before publication)" and is not a "Draft". Is this a draft revision?

#2890364: Replace all uses of "forward revision" with "pending revision" is about trying to pick less-worse machine names for content moderation before it's marked stable. So the question is whether draft_revision is less worse than forward_revision as a machine name. It might set precedent for user-facing names as we add more workflow features to core, but we can also always refine user-facing labels in the future.

Edit: But I guess it'd be pending_revision based on the above.

Feel free to call me a drive-by commenter, but this issue seems to be stumbling a bit on the "Clarify" part. Reading through all this my brain is like, "wha?" Is there a list/chart of all the states and their relationships to each other, so it would be easier to see the whole picture?

Everywhere the word "history" shows up, do we even need the word revision or version in front of it?

In #9, definitely agree that pending is better than forward.

This is the issue I am most concerned about for getting Content Moderation stable.

Here it has digressed a little into should we change user facing instances of "revision" to "version" or not.
Where as the forward / pending / draft debate has been sectioned off into #2890364: Replace all uses of "forward revision" with "pending revision".

Should this issue switch to a "task" with an updated title and issue summary to focus on "revision" Vs "version"?

For the 'revision' vs. 'version' part, we had *a lot* more discussion in #1643354: [Policy, No patch] Overhaul the entity revision terminology in UI text, but that issue was also not able to reach any meaningful conclusion, so I vote to follow @webchick's comment from #1643354-127: [Policy, No patch] Overhaul the entity revision terminology in UI text and wait until we have some actual usability testing for the revision functionality.

Since we will most likely keep using the word 'revision' in code, and UI labels can always be changed at a later date, this should no longer block Content Moderation from becoming stable.

For the 'forward revision' vs. 'pending revision' discussion, we seem to have unanimous support for 'pending', so let's do that in #2890364: Replace all uses of "forward revision" with "pending revision".

I fully support this decision: UI text can be updated in any minor release based on the findings of usability testing sessions, whereas any change in code terminology would need a BC layer. Let's get that done based on the consensus reached here. If it turns out users understand "version" better than "revision" (or X better than "pending"), we can always add the BC layer, if we really feel the disconnect between UI and code terminologies is unbearable.

Adding resolution regarding #2890364: Replace all uses of "forward revision" with "pending revision" to issue summary