Problem/Motivation

Our terminology for multiple past versions of a node, and the business logic around it, is confusing, outdated, and limited. So is the functionality, especially if we want it to apply to more than just nodes. Let's fix.

Proposed resolution

Define words thusly:

Entity
A data object. Has a unique ID within the keyspace of "Entity Type". (Vis, all nodes nids are in the same keyspace, but separate from user uids.)
Revisioning
The system and process of maintaining multiple historical and future versions of an Entity
Revision
A particular historical variant of an entity. Each has a unique ID within the keyspace of "Entity Type-Revisions". (Vis, all node vids are the same keyspace, but separate from user vids.) That is, the Revision history of a Node is a list of Revisions. (This is no change from now; revisiting this term is punted to a later issue.)
Default
The Revision that will be selected if you load an Entity by ID for viewing, but do not specify a version. node_load($nid); gets back whatever the "default" version is, which may or may not be the most-recently-edited. There is some disagreement about this term. Currently the leading alternative is "Primary".
Active/Working *
The Revision that will be selected if you load an Entity by ID for editing, but do not specify a version. This will need to be enforced by UI workflow, since editing is a UI workflow. Note that this may not be the same as the Default version. * There hasn't been a consensus reached about this term.
Published
A boolean Property (or rather, foreign entity referencing to it if we go with the plan proposed at the WSCCI/Entity sprint in Paris) of a Revision (not of an Entity) that indicates if non-administrative users should have access to the entity. This has no impact on entity_load(), only entity_view(). May or may not be used on a given entity type.

Access to non-default Revisions of an Entity is controlled separately (different permission, etc.) from access to the entity administration system.

All data storage assumes a possible lookup of any version. A denormalized structure for the default revisions only should typically be maintained for performance reasons.

Remaining tasks

Agree on the above, then create issues to make it happen in core.

All of the entity system refactoring from the Entity/WSCCI Sprint

User interface changes

Still TBD.

API changes

- Add a standard, simple way to make custom entities versionable.
- Switch from CRUD to CRAP. (Really, seriously, this needs to happen.)
- Possible changes to variable and method naming per the above.

Original report

It turns out that version is the commonly used term, so let's go with that as well on the entity API level. Actually revision seems to be specific to the use-case of having document revisions (= node module). So entity api should move to versions, node can stay with "revisions" in its UI.

Related, we might want to discuss the terminology around "live version" vs. "current version" for API level as well. Any opinions on that?

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Crell’s picture

"current" is too vague. "live" or "active" make more sense for indicating "the default revision that is the real thing right now", which may not have anything to do with what is most recent, or currently being worked on.

bforchhammer’s picture

Thinking in terms of a document management workflow, how about "published version"?

Bojhan’s picture

I don't get why this is tagged "Usability" are we going to change this in the UI?

Crell’s picture

I presume we would change the UI. Having it say "revision" in the UI and "version" in the code is a bad idea. That's never worked out well for us. :-)

jstoller’s picture

It seems like changing the UI is the real driver here, isn't it? I mean, a developer is far more likely to understand the term "revision" than a site builder or editor. I know I've had requests from bewildered users to change "revision" to "version" on sites.

I would recommend against using "published" or "live" in this context. "Active" makes more sense, if for no other reason than newly created content can be active without being published.

fago’s picture

Issue tags: -Usability

>So entity api should move to versions, node can stay with "revisions" in its UI.

When creating the issue, I thought about the code change only. More specific, I only thought about the entity-generic code. I don't think that generic API concepts need to have UI implications? (but could have of course)

@tag: Not sure where that comes from. Removing for now.

webchick’s picture

Status: Active » Postponed (maintainer needs more info)

I agree with Larry that calling the same thing two different things in the UI vs. the API is not something that makes a lot of sense to me. And unless we have some kind of data/evidence that "Version" is somehow wildly more discoverable/obvious than "Revision," (a sampling of screenshots from other projects, perhaps?) I'm not sure I understand the point of this change.

tstoeckler’s picture

I think that, because 'version' is a much more generic term than 'revision', we should definitely use it in the Entity API, i.e. Entity::getVersionId (vs. the current Entity::getRevisionId).
We could still use $node->rid and "Revisions" for the UI in node.module.

jstoller’s picture

I would argue strongly against fracturing our terminology. If there I a good reason to use "versions" over "revisions" then we should do so everywhere. If not, then we should continue using revisions everywhere. Using different words in different places is only going to confuse things.

I can offer anecdotal evidence that users understand the word version far more than revision, but I don't have any solid data to back that up. Webchick's right that, if we're going to make such a big change, we should do so based on actual evidence and not guesswork. I would suggest that someone interview a statistically significant number of non-Drupal using people and see how well they understand the term "revision", relative to "version". Then we'd have something to base a decision on.

tstoeckler’s picture

Not tightly bound to #9, just maybe to one more argument: To me this could be like the entity label a.k.a. $entity->label() is the node's title a.k.a. $node->title or the comment's subject a.k.a. $comment->subject.

So we make the general assumption, that our entities will have something like a label, but in different contexts different terms for that label make more sense than actually saying "label" everywhere.

That is how I could see the entity's version a.k.a $entity->getVersionId() corresponding to a node's revision (which is already, strangely $node->vid).

Again, I'm totally not married to this.

fago’s picture

Title: rename revisions to versions » overhaul the entity revision terminology
Status: Postponed (maintainer needs more info) » Active

I would argue strongly against fracturing our terminology. If there I a good reason to use "versions" over "revisions" then we should do so everywhere. If not, then we should continue using revisions everywhere. Using different words in different places is only going to confuse things.

ok, it looks like the idea of having entity versions and node revisions isn't something we can agree upon. I don't want to go for renaming node revisions or versions (that's a really different issue to me), so let's stay with entity revisions for now.

Still, can we get an agreement on going with "active revisions"? It's the terminology of that the d7 entity api module patch uses as well: #996696: Support revisions in Entity API. In comparison to "live", I'd prefer "active" as it's not so easily confused with the node publishing state.

webchick’s picture

Issue tags: +Needs usability review

I don't see a particular problem with that, but we should ping the UX folks, as well as the folks at #218755: Support revisions in different states who have an implementation of the 'live' flag.

sun’s picture

Title: overhaul the entity revision terminology » Overhaul the entity revision terminology

IMO we badly need to get rid of overly generic terms like "active" or "status." We need precise and concise flags and terminology instead, and yes, we need multiple flags.

It's unclear to me whether "active revision" targets the existing revision reference.

If if it means the existing, then that revision reference actually means the published revision.

If there is an additional meaning, then we need to add a separate property + value. But let's please not try to improve the terminology based on an old and outdated multivariate property, which doesn't really know what it is and which tries to bundle too much business logic into a single thing.

In any case, I wouldn't have an idea what an "active revision" is. Can there be an inactive revision? And if so, what exactly means that?

jstoller’s picture

For context, I'm going to talk in terms of nodes, but this would apply more generally to other entities as well.

The "active" revision is the one referenced in the {node} table. It may or may not be published/live, but it is the revision which Drupal sees as the most important. In other discussions, this revision is often labeled as the "current" revision and contrasted with the "latest" revision, but I personally have always found the distinction between current and latest to be confusing.

I'm not tied to the term "active", but I think it's probably the best option I've heard so far.

If changing "status" to "published", or "live", is on the table, then that has my vote as well! Either of those terms would be far more descriptive. As a side benefit, it would also open up the possibility of a future "state" field which references an arbitrary workflow state for entities (in the past there was concern about confusion between "state" and "status").

Crell’s picture

The "live, version that anon users see at node/X" needs to be the one in the node table (or equivalent). Whatever it's called, that needs to be the "default if you don't specify otherwise" version/revision. (I'd prefer version as well, personally.) That's a straight up performance concern.

jstoller’s picture

@Crell, yes, but the version referenced in the node table that is seen at /node/X may or may not actually be "live". Case in point... When I first create a node and save it, but do not publish it, then the node table will reference my latest revision, so that revision is "active", but it is not yet "live".

I think "live" implies "published", which isn't always the case. "Active" more generally indicates a level of importance, without implying a publication state.

fago’s picture

If if it means the existing, then that revision reference actually means the published revision.

That's totally node-centric terminology (and confusingly overlaps with node.status). Entity API terminology should make sense for any kind of entities though, thus my custom entity type X might not get "published" at all. Still, one revision/version is the one I get when I load one entity. Calling it "active" makes sense to me, it's the one "in use".

jstoller’s picture

The only other terms I can think of that seem relevant are "prime", or "primary", but I think "active" remains the best choice. Does anyone have a problem with the term "active"? If not, then can we call it decided and move on?

webchick’s picture

I also think this makes sense, and not sure I understand sun's concerns. To me "Active? Y/N?" aptly describes what's happening.

I do think though that on the front end here we'll want to keep the checkbox on the node form that toggle the "active" flag labeled as "Published" (or "Live" or whatever is eventually decided in #218755: Support revisions in different states) even though it clashes with the name on the back end. I realize this conflicts with the feedback given above that we shouldn't call things differently on the backend vs. front end (re: "version" vs. "revision") but here we're not talking about changing the name of a concept to be different between front and backend, but merely the label with which to toggle a flag in the UI, and in those instances, we always lean towards what makes sense to users, rather than exposing implementation details. (E.g. we label permissions checkboxes as "Human readable name" even though the machine name may be very different from what's shown).

webchick’s picture

Status: Active » Reviewed & tested by the community

And since this looks like consensus, but not unanimity, marking RTBC.

Bojhan’s picture

Agreed with webchick's assesment :) +1 on that usability review

Crell’s picture

I'm fine with "active". I just disagree with keeping "revision" instead of "version." :-)

jstoller’s picture

The current patch in #218755: Support revisions in different states maintains both a "Published" checkbox and a "Set as live revision" checkbox, on two separate tabs. This seems like a usability nightmare which still needs to be sorted out, but I think the idea was to get the base patch in and then fix the form later.

My own opinion is that we should never have a separate checkbox to set the active revision—that needs to be part of the publishing process—but perhaps that is a conversation for the other issue.

jstoller’s picture

Status: Reviewed & tested by the community » Active

While we're talking terminology, is changing "status" to "published", or "live", an option?

jstoller’s picture

Status: Active » Reviewed & tested by the community

Oops. Didn't mean to change the status.

webchick’s picture

Status: Reviewed & tested by the community » Needs review

Looks like this still needs review, unlesss we want to split into sub issues.

Changing a name of a concept in Drupal I feel needs significsnt redesrch into what other projects do, since we are agreed we don't want to call it revisions in the ui and versions in the api. So let's start gathering some screenshots; were not introducing a ux regression for something with no tangible benefit.

sun’s picture

since we are agreed we don't want to call it revisions in the ui and versions in the api.

I don't think there's an agreement on that yet. I'd be fine with differing terminology, if that's what the standard/industry uses. Typical case of DX != UX.

And it would definitely not be the first term that's different. Just try to find a "node" in the UI - good luck. ;)

Contrary to that, "revision" and "version" are pretty much synonyms of each other in common speech. That's like calling the overlay a modal window or even popup if you will, the essence is identical.

In general, we need to get over the idea of a hard-binding between developer terminology and user terminology anyway. That intended binding is bogus in itself either way, because it only applies to English. Just ask a Spanish, French, or German user what a "user", "account", "node", or "content" is. ;)

User interface terminology is detached from the terminology being used in code, by design.


Regardless of that, I've the impression that there's an unhealthy mix of different understandings of the problem space in this issue.

- Some people are talking about node/entity revision improvements, taking an ideal world into account.

- Some people are talking about entity revision clarifications, which do not attempt to take other issues and an ideal world into account.

As a result, "active" or "live" makes no sense to some, whereas it makes total sense to others.

I'm missing a clarification for what we want to clarify the terminology for.


re: #18: @fago:

Yes, a "published version" is centered around a content publishing workflow. Alas, only nodes have revisions and a content workflow in HEAD, so that's the ultimate measure :P

As soon as you apply "active version" to nodes, and as soon as we have a better content editing/publishing workflow in core, the "active" version would likely point to the "published" version. If the "active" version was pointing to a unpublished version, all hell would break loose. ;)

And yes, that is what the current {node}.vid property essentially does in my mind: It points to the published version of the node.

Obviously, we don't have a nice and mature content publishing workflow in core yet, so as soon as you unpublish the node (and create a new revision), {node}.vid will point to an unpublished version. But that particular bug really shouldn't be the measure for determining a proper design and terminology. ;)

The argument that some entities might not have a publishing concept at all is completely irrelevant for me. If there is no publishing concept in the first place, then all versions are published by default. In turn, it is still the "published version." The only difference is that there is no "latest unpublished/draft version."

sun’s picture

However, if you do not want to take other issues and possible entity revisioning improvements into account, then the proper and concise terminology is:

$entity->latestVersion

That is factually what the current pattern of {node}.vid is. It's neither "active", "live", nor "published", nor does it imply anything else. It is the most recently saved revision/version, and that's it.

jstoller’s picture

@sun:

Perhaps I'm missing something, but I haven't heard a single reason why we should change from "revision" to "version" in the API. I actually think we should change it in the UI, for UX reasons, and if that happens then I agree it should be changed in the API as well. However, as Webchick rightly pointed out, I have no hard data to support that request. All I have is anecdotes and instinct. But for me the driver is non-technical content editors who don't know what a node is. My instincts also tell me that developers are far more likely to understand what a revision is, making API changes much less important of an issue. Especially since, as you pointed out revision=version and everyone developing for Drupal seems to know that. So, other than saving one character when typing, what is the motivation for changing the API without changing the UI?

As for entities without a publishing concept... They may exist now, but I'm not so sure they should. At the moment I can't think of a single example of an entity that couldn't benefit from having a published flag. Nodes, comments, users, relations, contacts, field collections, profiles, media, beans, groups, products, etc., all can conceptually be published, or not. I also believe they would all benefit from revision support. And, of course, anything that's revisionable should support the concept of an active version, to permit moderation. If we are talking about an ideal world then I also think every entity revision should support arbitrary state designations, but I'll save that battle for another day.

Crell’s picture

sun, there's a subtle but very important distinction that your comment misses, which is at the heart of the issue.

node is, at this point, a denormalization table. That's it. node_revision is the real table. Field tables have the same structure. It's a denormalization for... the *default* revision of a node that should be retrieved if you don't ask for a specific revision.

The default revision/version may or may not be published. Really, that's a separate concept. Published, on a node, means "a non-admin user should be able to see this". It's an access flag. That may not be the same as "this is the default version that gets shown for anonymous users who don't otherwise specify a revision." If anything, published the access flag should be a property of a revision, not of the entire node. That way publishing or unpublishing a node at some preset time becomes simply switching the default/active/live/whatever revision.

Also, $entity->latestVersion is the assumption made by core today, yes. It is also a buggy and flawed assumption that adds a few hundred lines of code and several extraneous queries to every workflow module out there, because that assumption is *wrong* if you want to do "save as draft" functionality or any sort of edit-approval process. Workbench Moderation, for instance, has to do a double-save of a node just to hack around that core bug. That's the exact assumption/bug that #218755: Support revisions in different states is trying to fix.

The more I look at it, the more I think it's absolutely critical that we divorce revisioning/versioning as a concept from the idea of published. Published is an access control mechanism. It is not, at all, a version flag. That core currently merges versioning and ACL is one of the chief reasons that content moderation is so bloody hard to do well in Drupal right now. Let's fix that, starting with properly phrasing the question (aka, terminology).

jstoller’s picture

Amen!

tstoeckler’s picture

Re @jstoller #30:

As for entities without a publishing concept... They may exist now, but I'm not so sure they should. At the moment I can't think of a single example of an entity that couldn't benefit from having a published flag. Nodes, comments, users, relations, contacts, field collections, profiles, media, beans, groups, products, etc., all can conceptually be published, or not. I also believe they would all benefit from revision support. And, of course, anything that's revisionable should support the concept of an active version, to permit moderation. If we are talking about an ideal world then I also think every entity revision should support arbitrary state designations, but I'll save that battle for another day.

Don't save it for another day, just for another issue: #1295148: Maintain common properties/statistics about entities :-)

agentrickard’s picture

@Crell is dead-on in comment 31. What we are trying to convey in the concept of active / live is the VCS concept of HEAD. That is, the default version of the data that you will interact with unless you explicitly ask for another version. That explicit ask is the task of the version/revision control system and UI.

For entities that support published/unpublished, that flag is entirely independent of this property. The "HEAD" state of a node may well be unpublished.

Putting in place a name for "the current default version" is key to advanced (but user-expected) workflows in core. So let's nail down a name we can live with in code and then let the UX folks make it nice for end users.

Options on the table -- and I think these would apply to any entity type that supports versions.

  • active -- decent option, indicates what is being worked.
  • default -- dry, but possibly the most clear.
  • live -- potentially confusing with a publishing workflow.
  • head -- technical, very clear to coders.
  • tip -- synonym for head.
  • current -- potentially confusing with a publishing workflow.
  • primary -- possibly a good option, but "default" may be better.
  • principle -- synonym for "primary"
  • root -- technical term for starting point.
  • base -- synonym for root. Decent option.
  • baseline -- synonym for base.
  • working copy -- potentially misleading? Might be very clear for UI though.
  • main -- synonym for head.

Writing this, I actually like Default, which is a term we use elsewhere -- see settings.php -- to represent a very similar concept.

In regards to other systems, these terms are all so very similar that there is no consensus. See, for instance, http://wikipedia.org/wiki/Revision_control

jstoller’s picture

Re #34: I like "active" or "default". I might also be OK with "primary" or "prime" (not listed above, but a synonym for primary). "Main" is a distant fifth choice. All the rest seem too techie, or too much like a workflow state.

Originally I preferred "active", but reading these last few posts, I think "default" may actually be a better option. Thinking about it from a very literal workflow perspective, the most active revision is probably the latest revision, since that's where all the activity is. So the current default version may not be active at all. It could be old and abandoned, but it is still the default. This means we have properties like $node->isDefault, which I can totally live with. Perhaps it is dry, but I like the undeniable clarity.

fago’s picture

Published is an access control mechanism. It is not, at all, a version flag.

Totally, yes! That's why I dislike live or published, it's make the relation to "published" confusing.

Yes, a "published version" is centered around a content publishing workflow. Alas, only nodes have revisions and a content workflow in HEAD, so that's the ultimate measure :P

It's a main use case, but for sure not the only that counts. E.g. field-collections have no publishing state, as they just follow their host entity, but still having revisions makes a lot of sense for them. So for field-collection, the concept of publishing is irrelevant and does not apply, still there is an "active revision" or howsoever it's called.

Or take relation entities, no publishing concept - still versioning makes sense.

jstoller’s picture

As for the revision/version debate, here's a quick screenshot from Wikipedia. They seem to use revision and version interchangeably in their UI. Though in most cases it looks like they favor "revision" when talking about a collection (i.e. "revision history" or "selected revisions"), while they favor "version" when talking about a single instance (i.e. "current version").

Revision control_ Revision history - Wikipedia, the free encyclopedia.jpg

jstoller’s picture

@fago, as I argued in #30 above, perhaps relation and field collection entities don't currently have a publishing concept, but they certainly can and in my mind should. The ability to publish and unpublish relation entities would only open that module up to more use cases.

stevector’s picture

+1 for "default" as the name to indicate "what is the vid I will get if I just call entity_load($entity_type, $id)." I agree that "live" is confusing because it implies that an anonymous user can access some version of that entity which as sun points out is not the case with an "unpublished" node.

Crell and agentrickard are correct that the need for a term different from "latest" or "last saved" is tied to any sort of "save as draft" functionality. If we have a "save as draft" button then any revision/version created with that button is the "last saved" one and it is probably not the should come back for a give call to entity_load(). This concept of a saved "forward revision" is necessary for pretty much all of the contrib modules workflow modules like State Machine, Workbench Moderation, ERS, Revisioning, Maestro and Workflow. In the in-development version of State Machine 3.x, "active" is used to indicate "this is the version/revision that is being worked on/edited most recently." In the case of a published "About Us" node, there is a publicly available revision accessible at node/123 but it is the "active" revision that gets loaded to node/123/edit.

I'm trying hard to form an opinion on "revision" vs. "version" and I just don't have one.

If we can at least get consensus on "default," I'll update the patch in #218755: Support revisions in different states

Crell’s picture

So then, it sounds like we have:

Entity: A data object. Has a unique ID within the keyspace of "Entity Type". (Vis, all nodes nids are in the same keyspace, but separate from user uids.)

Revision/Version: A particular historical variant of an entity. Each has a unique ID within the keyspace of "Entity Type-Versions". (Vis, all node vids are the same keyspace, but separate from user vids.)

Default: The revision/version that will be selected if you load an Entity by ID, but do not specify a revision/version. node_load($nid); // Gets back whatever the "default" version is, which may or may not be the most-recently-edited.

Published: A boolean Property (or rather, foreign entity referencing to it if we go with the plan proposed at the WSCCI/Entity sprint in Paris) of a Revision/Version (not of an Entity) that indicates if non-administrative users should have access to the entity. This has no impact on entity_load(), only entity_view(). May or may not be used on a given entity type. (Which types it matters for are irrelevant; if it's more than one, then it must conceptually be possible on any.)

Right?

agentrickard’s picture

Right by me. And the 'default' version is stored in any de-normalized tables.

jstoller’s picture

Published: A boolean Property ... of a Revision/Version (not of an Entity) that indicates if non-administrative users should have access to the entity.

@Crell: By default, are you thinking that non-admin users will be able to access any revision with it's published flag set—in which case setting one revision to published will generally mean unsetting the flag on any previous versions—or are would you limit non-admin users to only accessing a published revision when it is also the default revision? I had been assuming the latter.

Other than that, it all sounds good to me.

@stevector: Reading your description of State Machine, I'm pulling all support for "active". I now agree 100% that "default" is the best term for the job.

fago’s picture

If we can at least get consensus on "default," I'll update the patch in #218755: Support revisions in different states

"Default" sounds good to me as well, so does #40!

webchick’s picture

#40 sounds good, it still leaves the question of revision vs. version open. The screenshots from Wikipedia use "Revision" consistently outside of help text, so that is one point in favour for leaving that the way it is. Any other screenshots?

agentrickard’s picture

@jstoller

YES: "you limit non-admin users to only accessing a published revision when it is also the default revision" .

You need special permission -- granted by the revision system -- to view any version other than default.

Crell’s picture

Agreed with #45, with the caveat that "admin" vs. "non-admin" is too coarse a distinction to make. "administer nodes" is a permission that needs to go away. :-) But yes, "access revisions other than the default" is a separate permission.

I still prefer version to revision, but as above have no data to back that up. If we keep "revision" and do the rest of #40, I'll mutter a bit and go on with my life (unless someone else has data either way).

jstoller’s picture

Here's a screenshot from Google Docs. This isn't looking good. :-(

Joe Wise letter of support - Google Docs.jpg

jstoller’s picture

FileSize
35.94 KB

Yay! Here's a solid one for the "version" crowd. This is from the new built-in revisioning in Mac OS X Lion. The users of this feature most closely resemble the users I'm trying to support, compared to other examples so far, so I'd give it some weight.

Menubar.jpg

jstoller’s picture

Wordpress also uses "revision".

Revisions ‹ Wordpress Test — WordPress.jpg

Crell’s picture

jstoller: Although that screenshot supports my preference, I dispute that "Mac users who aren't bothered that Apple decided to change 20 years worth of ingrained UI knowledge for no good reason" is our primary target audience. :-)

In either case, it does look like the industry standard is inconsistency. :-/

jstoller’s picture

@Crell, trust me, there are many changes in this OS that I'm less than thrilled with--I'm still struggling with which way to flick my scroll wheel and I certainly miss the scroll bars in my windows--but of the systems I've looked at so far, Mac OS is the one most targeted at non-technical users.

In any case, I would suggest that looking at existing systems is not the best way to make this decision. "Revision" and "version" are both perfectly accurate terms and both are used in other products. The question I'd ask is not "which is used more," but rather "which is better understood?" Could we develop a simple survey to sus out the public's understanding of these two words and send it out to some people? Note that "people" in this context does not mean Drupal developers. I'm talking about people who don't know what a CMS is, have no idea how to protect their WiFi network, and get hard-drives and RAM mixed up when you talk about computer memory. Real people. Those are the people I need to train to manage content on my websites.

webchick’s picture

Status: Needs review » Reviewed & tested by the community

"Save a version" is Apple's version of "Save as" (because apparently they are special enough they think they can change industry-standard patterns that have been there for 40 years on a whim :P), so this is not the same thing. The other examples OTOH are exactly the same thing. And the standard is clearly "revision." So IMO that settles that.

Back to RTBC on #40 + sticking with "Revision."

jstoller’s picture

@webchick: "Save a version" is not a replacement of "Save as". Apple implemented a version control system for documents. Once you've initially saved a document, "Save a version" replaces "Save...". It forces the application to save a snapshot of the current state (though there is also an auto-save thing happening). You'll note the "Revert document..." option, a few items below, which allows you to revert your document to an earlier snapshot. I would argue that this is the exact same thing we are talking about.

The screenshots posted are just a few systems that I had readily available to me, but I do not deny "revision" seems to be the most used term among them. That said, tradition is not always good. In this case I feel a little like we're jumping off a bridge because Wordpress told us to. All I know is that I've experienced people being confused about the term "revision" first hand. The word just isn't used much in everyday speech. It doesn't really matter to me which term is used in the API, but I would suggest considering a more Wikipedia-like approach, at the very least, when it comes to the UI.

sun’s picture

UI-wise, the screenshot in #37 of Wikipedia made most sense to me; i.e., "Revisions" always used when referring to multiple/all, "Version" always used when referring to a single one.

That also seems to be in line with Apple's "Save version", which refers to a single version.

webchick’s picture

Title: Overhaul the entity revision terminology » [Policy, No patch] Overhaul the entity revision terminology

Since Dries seems to be in an RTBC queue frenzy atm :) changing title to be appropriate.

Bojhan’s picture

Can anyone explain to me whats being proposed here?

Crell’s picture

I've added an issue summary with what I think the current discussion is, based on #40 and following. I also added "Active" for the "Default-when-editing" version following discussion with stevector, since that's the term Workbench uses.

dixon_’s picture

A boolean Property (or rather, foreign entity referencing to it if we go with the plan proposed at the WSCCI/Entity sprint in Paris)

Although I was the one suggesting this in Paris, I suggest we forget about that foreign entity for now. It essentially means moving something like Flag module into core, which we don't have time with. Let's stick to keeping 'published' as a property and move forward.
However, I'll open up a separate issue about that, so we don't forget about it. Because it is rather nice :)

webchick’s picture

Status: Reviewed & tested by the community » Needs review

Wait. Why does the issue summary say "version" when there's been no research to support it? Also where did *both* active *And* default come from. Sigh. Still bike shedding I guess. :(

Crell’s picture

"Version" made it into the summary based on #54. Debate on that point is still welcome. :-)

zhangtaihao’s picture

I'm not sure if I've missed it in a previous post. I apologize if I'm repeating what someone else has said.

It seems to me, precisely because "version" is a generally better understood term, that it is at least somewhat more likely to be used in a content model. Where a content type represents documents whose versions are as significant as the documents themselves, "version" might be a field. In this instance, would having Drupal say "Edit version" seem confusing?

EDIT: I presume we're not just talking about code, but rather the general terminology in Drupal (framework or UI).

jstoller’s picture

@webchick:
"default" comes from our discussions here and seems to have good support.

The new "active" comes from its use in State Machine and Workbench, as noted by stevector in #39. There hasn't been much talk about it, but there's been no dissent as of yet and the term has my vote.

As for the continued revision/version debate, there hasn't really been anything substantive to support either term. What's currently proposed in the issue summary has as much support as anything else. I think continued exploration of if an when we should use "version" in the UI would be beneficial, but I can't speak to the API.

webchick’s picture

"As for the continued revision/version debate, there hasn't really been anything substantive to support either term."

Are you serious?

- It's already called that, and has been for 9 years or something. Drupal's usage has increased 8000-fold in that time.
- We don't have any documented usability issues in the queue about this being a barrier to Drupal adoption. Nor on the DX side.
- Wikipedia, the most widely-used application of this technology, uses "Revision" for all headers, buttons, column headers, and other major labels. They only use the word "version" in help text.
- Google Docs, the second-most-wildely-used application, also uses "Revision."
- For extra added bonus, so does WordPress.

The only example of using "Version" for this that has been provided is Mac OSX which is a desktop system, not a web system.

From http://www.useit.com/alertbox/991114.html

If 80% or more of the big sites do things in a single way, then this is the de-facto standard and you have to comply. Only deviate from a design standard if your alternative design has at least 100% higher measured usability.

So in what way is this not as clear-cut as possible? Why are we still arguing about it?

webchick’s picture

And the addition of "active" in the mix makes the distinction between "default" and "active" incredibly unclear to me. Maybe I just need to sit with it longer, I dunno.

Crell’s picture

webchick: Consider this example:

node 5. It has a bunch of revisions. Revision 10 is the revision you want to display when normal people go to /node/5. However, there's a new draft that's still being worked on, Revision 12. If I click Edit, I want to have my form prepopulated by revision 12, not revision 10, so that I don't lose all of the changes that people made already in revisions 11 and 12.

Revision 10 therefore is the Default Revision.

Revision 12 therefore is the Active Revision.

At some point in the future, Revision 15 will get approval to go live. It will then be promoted to Default (aka, moved to the denormalized node table). At that point Revision 15 with be both Default and Active, until someone starts working on a new draft again. In the degenerate case of no draft-save ability, Default and Active mean the same thing. But that is a *degenerate* use case, not a *standard* use case, at least from an API perspective.

Make sense?

sun’s picture

Um, I can't really make sense of why we're purposively using an obscure, different term. Why don't we call the revision that refers to latest draft the "Draft Revision" or "Latest revision"?

jstoller’s picture

@webchick, let me elaborate...
There has been no research presented indicating the people's relative comprehension of the words "revision" and "version". All we have are four screenshots from other systems—two use "revision" exclusively, one uses "version" exclusively and one uses a mix of terms—so I question the statistical significance of this dataset. That is why I said there was no substantive support. What we are left with is historical precedent, which is fine, absent a compelling reason to change, but obviously there are people here who see compelling reasons to change.

The reason I'm still talking about this is because I'm tired of explaining to users what a revision is, only to have them ask me why I don't just call it a version. I had actually been meaning to post this as an issue myself, but didn't get to it.

I don't see this as a DX issue, or even too much of a site builder issue, so I wouldn't expect it to be a big obstacle to Drupal adoption, per se. In my mind it is a UX issue, impacting non-technical site users most heavily. You keep minimizing Wikipedia's use of "version" as being "only in help text," but that makes a big difference to comprehension. By using version interchangeably with revision, the former helps define the latter, minimizing confusion and improving UX. I also see no reason to dismiss Mac OS X for being a desktop OS, given we're talking word comprehension and not HTML interfaces.

Now, I myself have not seen evidence of widespread developer confusion stemming from the use of the word revision in the API. So when it comes to code, I don't see a need to break with precedent. I wouldn't object to the change, but I'm certainly not calling for it. All I'm suggesting is that we use "version" in the UI, in some instances, bringing us more in line with Wikipedia and Mac OS X.

@sun:
"Draft" is a workflow state and "latest" is a temporal attribute. It is entirely possible that the "active" revision will not be the latest revision, or in a draft state.

Now that you mention it, perhaps we should add "latest" to our vocabulary list up above, if for no other reason than to differentiate it from "active" and "default".

Crell’s picture

I don't feel strongly enough about revision/version to hold up #218755: Support revisions in different states if that's the only thing blocking it.

That said, for the love of Druplicon if you're going to change it in the UI, change it in the code, too. Both or neither. We do NOT want a repeat of taxonomy/category. (And Node/Content. The instant you leave core itself, the word node is thrown in your face and you have to learn that both words mean the same thing 99.4% of the time.)

"Latest", honestly, only sometimes has a meaning at all. It only means something in a linear revision process, which is not always the case.

jstoller’s picture

@Crell, if the UI uses both revision and version, then would you still have a problem with the code using revision exclusively?

sun’s picture

What confuses me about "active":

If there is an "Active Revision" then that means all the other revisions are not active. But yet, there may be a default revision which is used by default, but apparently and consequently, not active.

And what does active really mean? That the others are "passive"? I'm afraid, but this doesn't make much sense to me. :-/

jstoller’s picture

@sun:
The default revision may also be the active revision, in some cases, but that is not necessarily so. Take another look at Crell's example in #65.

If it helps, you can think of it like a git repository. Essentially "default" is whatever commit has been tagged for release, while "active" is roughly equivalent to "head". Some times those two things line up, but often they don't.

Crell’s picture

What jstoller said re Git. As for using both words, it would depend on how they're used. As a module developer I shouldn't have to think about whether I'm looking for UI text or variable names. It should be self-evident.

I can't help but wonder if there's also a language barrier issue here, because admittedly default vs. active is subtle in English, and no offense sun but it's not your first language. :-) (Which may indicate we want to pick something where the concept translates more easily for non-native speakers; I'm just not sure to what.)

fago’s picture

I don't see why we are discussing the term for an "active revision" when we don't even have support for something like that? If a module adds that, it can define the term for it itself.

That said, for the love of Druplicon if you're going to change it in the UI, change it in the code, too. Both or neither. We do NOT want a repeat of taxonomy/category.

Agreed, but that's not the same as the originally suggested entity version - node revision switch. Imo it's fine to have a generic term in the entity api, and another maybe more use-case specific term for a certain entity type. Example: entity label, node title.

agentrickard’s picture

@fago see #218755: Support revisions in different states. This terminology is blocking that support.

fago’s picture

yeah, I've look at that one but I don't see support for that "active revision" thing there either!?

fago’s picture

Oh, I see - with the possibility of having non-latest default revisions, something like that makes lot of sense and possibly should be added. E.g. always edit the *latest* revision by default.

Still, I don't see us supporting a "active revision" tag or something like that, so the discussion is pointless?

stevector’s picture

I don't think there's a patch yet that actually implements active/draft but we'll run into that very quickly if there is a "save as draft" button. I see "draft" as more self-documenting in the case of nodes. "Active" is more likely to get confused with what we're now calling "default." "Active" still might be the better choice as an entity-type-agnostic term where the given revision isn't being "drafted" by a person as a node is. "Draft" fits less well in my opinion for something like a Commerce entity.

Webchick is right there is not a clear cut case for changing revision to version and that the evidence presented actually goes the other way.

jstoller’s picture

I think it would behoove us to define a term for what we are now calling "active." Even if it isn't being codified in the API right now, there is a very good chance that it will be in the near future. And even if that doesn't happen, there's good reason to suggest a standard terminology for contrib to use.

I would argue strongly against changing "active" to "draft." Even for nodes. For starters, "draft" is a workflow state, which is not what we're describing here. But perhaps most importantly, at many points in an entity's life cycle, it may have a revision that is both published and active at the same time. I think it would be more than a little awkward to have a revision that was both published and draft.

cosmicdreams’s picture

We need a deadline: Can we bring discussion to a close by Sept 10?

jstoller’s picture

Can we start by defining what we're still discussing? It seems to me that there is general agreement on "default" and "published". There has been some mild discomfort with "active", but nothing better has been suggested. The contentious issue has been if/when to use "version" instead of "revision".

Does everyone concur with this assessment?

Active:

I'm still OK with this term. If you have a problem with it, then do you have a better idea?

Revision/Version:

I'm still of the opinion that most people out in the world have a better intuitive understanding of the word version than then word revision. I also understand that there is a precedence for using the word revision. So, in the absence of more elaborate research, I am suggesting we adopt a policy in the UI that's more like what Wikipedia does. Specifically, we use "revision" when talking about a collection (i.e. "revision history" or "selected revisions"), but use "version" when talking about a single instance (i.e. "latest version"). Much of this may be in help text, but I think including the word version will improve overall comprehension and thus improve UX.

When It comes to changing terminology in the API, I have no strong opinion. If we're essentially using "revision" and "version" interchangeably in the UI, then I see no problem with sticking with "revision" in the API.

Other thoughts?

Crell’s picture

I don't feel strongly enough about revision vs. version to hold up the rest of this issue and the renaming that needs to be done with it. I'm fine with leaving it as is and maybe circling back sometime in the future, maybe.

I think we're all on the same page otherwise.

RobW’s picture

If you're interested in the perceptions of a non-involved, fresh eyed, generally literate human:

  • I understand version and revision, especially in a context like http://drupal.org/node/1643354#comment-6231346.
  • The word revision is connected to the action of revising something. The first draft is not a revision, and a complete rewrite is not a revision. This makes me think that version would work in more contexts.
  • Active is a little confusing, but if the current editable draft can be something besides the latest, active makes sense.
  • Default makes sense from the point of a developer looking at the system from the inside out. Published makes sense from the point of view of a site user working with content.

Aaaand I take my leave.

klonos’s picture

Default makes sense from the point of a developer looking at the system from the inside out. Published makes sense from the point of view of a site user working with content.

++

Its far easier for devs/admins to be trained to know that "Published" means "default" than trying to explain what a "default" revision/version is to end users and site content authors.

jstoller’s picture

I will reiterate that "published" is a workflow state and is not equivalent to "default" in this context. The default revision might be published, or it might not be. Calling an unpublished draft "published" would be extremely confusing. We need a term to describe the revision loaded by default when an entity is called without specifying a vid, independent of said entity's workflow state. Default is still the most intuitive term I can think of.

In the end, I think (hope) that "default" and "active" will both be terms that are largely relevant only to developers. I believe we will be able to come up with a better UI to account for this, so from the users perspective they are just saving a draft, or saving and publishing content, but behind the scenes we can manipulate these flags appropriately. That, however, is a discussion for a different issue (#1776796: Provide a better UX for creating, editing & managing draft revisions.).

RobW’s picture

That makes sense. Default is so vague as to be almost meaningless, but active is already taken, staged is too developer and git-ey... It's awesome and important that people are looking closely at the ux of naming conventions, but unless we can redefine terms across all of Drupal at once it's not going to get appreciably better. This is nicely done with what there is to work with.

Alan D.’s picture

Is there a stalemate with the revision / version debate?

Regurgitating some of the other points already made, version is not as common as revision but is probably more accurate when defining an item in its current state. It is defined as "a form or variant of a type or original".

A revision "a result of revising".

"The original version" is the first type created.
"The original revision" is the first revision of the first type created.

"This version" relates to the current state.
"This revision" relates to the transition between two versions that resulted in the current state.

So Wiki wins, but...

From two of the biggest players in the SW market:

Microsoft uses version / versioning.
Google uses revisions

This suggests that internal UX testing has better results with consistent naming.

[Edit]
My interest in the general consensus is for #1785742: Diff module string review. Personally I don't really have a preference, but I would like to make this new branch consistent with the direction that Drupal is headed.

Crell’s picture

Ignoring revision vs. version, is there anything *else* here that we can't just move forward on and get done? We can circle back to that later if we want, but let's get the rest of this issue taken care of.

Pancho’s picture

Status: Needs review » Needs work

Hmm, I share the doubts about "default" vs. "active" revision.
Actually, I'm not happy with either.

I see two problems with the use of "default revision":

  • Firstly, "default" refers to some preset to start with or to fallback, and so everywhere in our UI it is used for admin presets. For example, in Workbench Moderation (which is clearly related to our efforts here), there is a "default state".
    Imagine a revision in "draft" state (which is set as default state) whereas the "published" revision is called "default revision". This is extremely confusing.
  • But even more importantly, the term doesn't work as differentiation. Finally we're having a (not necessarily published) revision-to-be-viewed we call "default" and another revision-to-be-edited (which is just as default even if called differently). Crell very nicely pointed this out in #65.
    However, even if the former happens to be denormalized in the {node} table, this actually means that there is not one "default revision", but two of them.

If we now call the revision-to-be-edited "active revision", things get even worse. "Active" is clearly associated with live, public, or at least the one to be viewed. (Rather than "active", the one to be edited is "passive", as we're ought to do something with it.)

Pancho’s picture

Status: Needs work » Needs review

There is no 100% clear terminology. But to do the best we can, I'd propose calling:

  • the revision-to-be-edited: "working revision" (or maybe "pending" revision, which might be the latest one or not)
  • the revision-to-be-viewed: "active revision" (or maybe "current" revision, which might be published/live or not)

Definitions:

default
"a selection automatically used by a computer program in the absence of a choice made by the user" (Merriam-Webster)
"the preset selection of an option offered by a system, which will always be followed except when explicitly altered" (FreeDictionary)
active
"marked by present operation, transaction, movement, or use" (Merriam-Webster)
"Currently in use or effect" (FreeDictionary)
current
"generally accepted, used, practiced, or prevalent at the moment " (Merriam-Webster)
"commonly known, practised, or accepted; circulating and valid at present" (FreeDictionary)
working
"assumed or adopted to permit or facilitate further work or activity" (Merriam-Webster)
"providing a basis, usually a temporary one, on which operations or procedures may be carried out" (FreeDictionary)
pending
"not yet decided; being in continuance" (Merriam-Webster)
"unfinished - not brought to an end or conclusion" (FreeDictionary)
jstoller’s picture

I have no problem changing "active revision" to "working revision". Really either one wold work for me. I see active as meaning that's where the activity is, while working means that's where the work is being done. Both are accurate. At the moment I'm leaning toward "working" as being more intuitive, but I have no research to back that up.

I would oppose using "pending" here as that implies you're waiting for someone to do something, which isn't the case. "Pending" is a workflow state and does not apply in this context.

I also do not like the idea of changing "default" to "current". To me, "current" implies "most recent" and that just isn't true. I'd have trouble referring to a two year old revision as "current".

I could maybe see changing "default" to "active". At the beginning of this thread that seemed perfectly reasonable to me, but now I'm not so sure. It just isn't a very active revision. I still think "default" is the most accurate term for what's happening. I could maybe see using "base revision", since that's what's linked to the entity's base table. Or possibly "primary revision", since it's the one revision we single out from the rest.

Pancho’s picture

It certainly depends on the perspective which revision can be considered "active". Some (including me) would argue from the perspective of the entity that the revision that is ready to display does something and so is active. Others (including you) would argue that the user is actively supposed to do something with the working revision. Seems to make it an inferior choice.

"Primary revision" sounds good though. We'd then have the "working revision" which is loaded on edit and the (denormalized) primary revision which is loaded on view.

Does that sound good to the others? I think it is pretty much what we can do to:
- keep the two "default revisions" easily identifiable apart,
- avoid false assumptions on the "published" status
- avoid naming collisions with adjacent concepts
And then let's see which naming decisions the UI thread comes up with.

Regarding revisions vs. versions, I'm fine with both, as long as we stay consistent between code and interface. Preferrably this should be a UX decision.

Pancho’s picture

Issue summary: View changes

Add issue summary.

Crell’s picture

Assigned: Unassigned » Dries

This thread has gone on long enough. It's a pure-bikeshed (there's no technical grounds for the decision either way), and has been discussed to death for months.

I have updated the summary to reflect punting on the revision/version question. I am therefore assigning this to Dries for a Final Edict And Decision(tm). Dries, if you want to delegate to a domain expert here I recommend either Steve Persch (stevector) or Bojhan.

Crell’s picture

Issue summary: View changes

Change summary to stick with Revision as the noun, not Version.

jstoller’s picture

I updated the summary to note the current disagreement around "default" and "active", indicating "primary" and "working" as the leading proposed alternates. Any of these terms are fine by me if we can put this to bed.

jstoller’s picture

Issue summary: View changes

Updated issue summary.

webchick’s picture

Can someone explain what this is blocking and why it's worth Dries (or anyone else) taking time to review this before feature freeze?

yoroy’s picture

Make it 'default' and 'active'. The relationship between those two words is clearer than between 'primary' and 'working'. Done :-)

yoroy’s picture

Psst, Crell: put this rtbc and get if over with ;-)

Crell’s picture

Status: Needs review » Reviewed & tested by the community

There's no more discussion to be had here beyond approval from on high.

webchick: Because this has implications for all API operations in the entity system and resolving this issue means we can actually be speaking the same language in a half dozen other issues relating to revisioning, entities, etc.

cosmicdreams’s picture

pinging this issue to see if can be marked as resolved. It appears we're operating under that assumption already. Please indicate if this is accepted thinking or not.

fago’s picture

Status: Reviewed & tested by the community » Needs work

I like the "default revision" wording and the rest of the summary, but I'm still not happy with "active".

First off, active vs default is rather confusing. Then as pointed out in #76, we do not need or use this term at all right now, what makes the distinction even more confusing.

I don't think there's a patch yet that actually implements active/draft but we'll run into that very quickly if there is a "save as draft" button. I see "draft" as more self-documenting in the case of nodes.

If a module implements such functionaltiy, it has to define its terminology well. It's pointless to define and/or document terms that are not used anywhere. Thus, I propose to remove the part about "active" from the suggested policy as well.

Dries’s picture

Assigned: Dries » Unassigned

I like all of this, except for 'Default' and 'Active'. It is not as intuitive as it should be and can be. I would recommend 'Viewing revision' and 'Editing revision'. You know, call it as it is ... seems a lot more intuitive and discoverable to me.

In other words:

Entity
A data object. Has a unique ID within the keyspace of "Entity Type". (Vis, all nodes nids are in the same keyspace, but separate from user uids.)
Revisioning
The system and process of maintaining multiple historical and future versions of an Entity
Revision
A particular historical variant of an entity. Each has a unique ID within the keyspace of "Entity Type-Revisions". (Vis, all node vids are the same keyspace, but separate from user vids.) That is, the Revision history of a Node is a list of Revisions. (This is no change from now; revisiting this term is punted to a later issue.)
Viewing revision
The Revision that will be selected if you load an Entity by ID for viewing, but do not specify a version. node_load($nid); gets back whatever the "default" version is, which may or may not be the most-recently-edited. There is some disagreement about this term. Currently the leading alternative is "Primary".
Editing revision
The Revision that will be selected if you load an Entity by ID for editing, but do not specify a version. This will need to be enforced by UI workflow, since editing is a UI workflow. Note that this may not be the same as the Default version. There is some disagreement about this term. Currently the leading alternative is "Working".
Published
A boolean Property (or rather, foreign entity referencing to it if we go with the plan proposed at the WSCCI/Entity sprint in Paris) of a Revision (not of an Entity) that indicates if non-administrative users should have access to the entity. This has no impact on entity_load(), only entity_view(). May or may not be used on a given entity type.

Hope that helps!

jstoller’s picture

@Dries, would you then suggest we change the isDefaultRevision property to isViewingRevision? That seems a bit confusing to me and I think that's the only place this terminology is used at the moment.

fago’s picture

Viewing revision - The Revision that will be selected if you load an Entity by ID for viewing, but do not specify a version.

We do not have an API that supports loading an entity *for viewing* - we have an API that supports loading an entity. It's the revision that will be selected if you load an Entity by ID, but do not specify a version - but that's not the revision for viewing only. Thus, to me default revision makes sense as long as the term "active revision" goes away. As stated already in #99 I agree that having *both* 'Default' and 'Active' is confusing.

Editing revision - The Revision that will be selected if you load an Entity by ID for editing, but do not specify a version.

That's not true - as pointed out we don't have that functionality. But if we'd have it I agree that editing versions would be a good term.

jstoller’s picture

I have to agree with @fago. "Default revision" makes WAY more sense than "Viewing revision" to me. Especially given the contexts in which the term is currently used. To me, "viewing revision" implies the revision currently being viewed, rather than the version that will be viewed by default. I just find it confusing.

"Editing revision" doesn't feel quite right to me, but at least it doesn't add more confusion. Of course, since it doesn't appear there will be anything in D8 codifying this term anyway, I'd be happy to punt it further down the road and see if we can come up with something better.

Crell’s picture

In the current core case, active and default revisions would always be the same. The reason to have "active" would be to standardize terminology for forward-revisioning, aka save-as-draft, aka any sort of content staging that doesn't involve multiple servers (which is a PITA). We should at least not make it hard for that to happen in contrib, and standardizing terminology can help there.

I defer to stevector on how necessary that is to do now.

effulgentsia’s picture

Assigned: Unassigned » Dries

Looks like this needs another comment from Dries.

jstoller’s picture

@Crell, with core's new support for forward revisions (thanks to isDefualtRevision()), the active (aka. editing, aka. working) and default (aka. viewing) revisions will likely not be the same. At least not on any of my sites. Users will edit the latest revision, which may or may not be the default, published revision. No module, core or contrib, should assume otherwise. That was the whole point of what we did in #218755: Support revisions in different states.

effulgentsia’s picture

Users will edit the latest revision

Is "editing" revision ever not equal to "latest" revision?

jstoller’s picture

The only sane default behavior I can think of is "editing revision" = "latest revision". In theory, that need not always be the case, but nothing in core provides for this since, as @fago points out, we have no way of tracking the "editing revision" of an entity.

I should preface this by saying that I was out a bit after #218755: Support revisions in different states got committed. The intention there was always that the latest revision of an entity is the one which gets edited by default. If that isn't the case, then I would see it as a big bug.

Crell’s picture

jstoller: I mean the core API allows for forward revisions, but the core application layer is not going to leverage it. So core wouldn't differentiate between the two.

Nearly all of our sites will run Workbench, though, so they would have a difference between active and default. Hence why I think the API is not complete unless we define what they're called, even if the core UI doesn't expose both words.

effulgentsia’s picture

But based on #102 and #108, it sounds like the core API has no concept of "active", "working", or "editing" revisions as distinct from "latest" revision. So, would "default" (for the vid in the {node} table) and "latest" (for the max(vid) in the {node_revision} table) be appropriate terms?

effulgentsia’s picture

Or, is the suggestion that we change the {node} table from having a single vid column to having a viewing_vid and editing_vid so that both can be distinct from latest?

jstoller’s picture

@Crell, I was under the impression that if an entity has a forward revision, core's default behavior when editing would be to use the latest revision, rather than the default, even without Workbench (or equivalent) installed. If that isn't the case, then in my mind core is broken. Also, if we can get some more movement on #1776796: Provide a better UX for creating, editing & managing draft revisions., to finish the work started in #218755: Support revisions in different states, then this will all be even more relevant.

@effulgentsia, there was some talk of adding a {node}.editing field, or the like, but there didn't seem to be much call for it and I assume it's out for D8 at this point anyway.

stevector’s picture

@jstoller, I do not think core's current lack of an editing/active revision means that core is broken. The version of #218755: Support revisions in different states that was committed removed the checkbox that marked a revision as "forward." So if someone just installs core they get the same revision behavior they've gotten in core for many versions.

The big difference in #218755: Support revisions in different states is that contrib modules will no longer have to actively fight against core to make forward revisions possible. In D7 Workbench Moderation, and every other forward revision contrib module, has to do a double node save to get forward revisions working. One save for the forward revision and then a resave of the "default" revision. That's the part that is now much easier thanks to #218755: Support revisions in different states

I would agree with you that core should provide the editing/active concept if there weren't new models cropping up. Workbench Moderation is built on premise that there is only one editing revision. However from what I gather of the Collections module , there's a use case in which a node may have different editing revisions based on the given collection. I don't know if it's a good idea to bake another assumption into core for this module to fight against.

Though, thinking about it a little more, Collections module might also be changing the "default" node based on the collection as well. So if that module needs to override "default" it could override "editing" just as easily.

Back to the point of this thread: I don't think core needs to decide between "editing" and "active" until core uses those concepts and right now it doesn't. #1776796: Provide a better UX for creating, editing & managing draft revisions. would be the place to do it.

I also agree with fago that "default" is better than "viewing" because entity_load() is used for much more than viewing an entity.

Dries’s picture

Fago wrote in #103: We do not have an API that supports loading an entity *for viewing* - we have an API that supports loading an entity. It's the revision that will be selected if you load an Entity by ID, but do not specify a version - but that's not the revision for viewing only.

Maybe I misunderstood your comment but ... it seems perfectly reasonable for someone to write code that says: "Load me the revision of this entity that currently gets shown to visitors", and then to carry on doing an operation on that revision without actually showing it. In other words, it is not because we don't always show the revision that we can't use the name 'viewing revision'.

I don't understand why the entity system can't have a notion of entities being 'viewed' and 'edited'. Reality is that the entity system exists in the context of a CMS, where things are being viewed and edited. We even built, and continue to build, a UI on top of the entity system. We don't need to abstract concepts like 'viewing' and 'editing' out of the entity system.

Would love to better understand why you think we don't have 'viewing' and 'editing' functionality.

jstoller’s picture

I don't want to speak for Fago, but here's my 2-cents. Viewing is one thing that you can do when you load an entity—it may even be the most common reason for loading entities—but it isn't the only reason why an entity might be loaded. Calling it the "viewing revision" is therefore inaccurate. The default revision may be viewed, but it is also the revision which will be exported into my third-party account management database. And some entities are never actually viewed by end users at all. They are just constructs used to organize other entities.

On the other hand, "editing revision" makes some sense, given there is no reason to load it other than to edit the entity, or to see the latest edits.

FYI, there is the start of a patch in #1776796: Provide a better UX for creating, editing & managing draft revisions., which attempts to add an isEditRevision() method to entities and an edit_vid column to the node table.

sun’s picture

Status: Needs work » Needs review

In terms of gradual improvement, I have to agree with @Dries. I've the impression we're shooting too far.

As in: From zero to hero. Skipping all steps in between. Coming from zero, just simply try to estimate what a hero will need, abstracting the heck out of it, just to be sure. As in, premature optimization.

That gets evident by the terminology discussion we're having. If you'd confront any normal human with the proposed terminology, he'd call you nuts.

In that sense, I think that @Dries' simplification on actual CMS revision needs is spot-on. Let's go from zero to there, to something that makes sense, and to something that can be explained to a human without getting shot-down. And only from there, we'll gain and have the usage data and experience to abstract further, in sensible ways.

Remember, this issue is about terminology only. There's nothing (or there shouldn't be anything) that would prevent contrib from introducing new revision terminology on top of the existing (or possibly even, replacing the existing).

So, all in all, "viewing revision" and "editing revision" are two uniquely identifiable states of an entity that can be explained in almost no time to almost any human on this world. Sounds like a simple, straightforward way to go. From here.

In D9, and 2016, the situation might look different. Especially after x.module introduced the new Y revision state. And if that proves to be a common enough use-case, we can certainly extend our core terminology to incorporate it. But there's no reason to "guess" that future upfront.

effulgentsia’s picture

In terms of UI (text shown to administrators), I agree with #116. How does that impact API then?

EntityInterface currently defines isDefaultRevision(). Do we change that to isViewingRevision() and add an isEditingRevision()?

EntityStorageControllerInterface defines load() (which takes no $revision argument) and loadRevision() (which takes a specific $revision_id). Do we change this to loadViewing() and loadEditing(), and/or introduce constants like EntityInterface::REVISION_VIEWING, EntityInterface::REVISION_EDITING, etc.?

effulgentsia’s picture

Also, what resolution do we need to achieve in this abstract issue vs. figuring out something concrete in #1776796: Provide a better UX for creating, editing & managing draft revisions.?

jstoller’s picture

I guess I just don't see what's so nuts about the term "default revision". It's not like default is a terribly abstract word. If I ask for a node and I don't specify which version I want, I get the default. Is that really so confusing?

Crell’s picture

sun: I think it's simply inaccurate to say that we have no idea what the "hero" will need. Between just the people in this thread, we have how many hundreds of hours of experience doing content moderation, staging, deployment, using entities for API purposes without displaying them to the user, syndicating via REST or Services, and dozens of other things that have nothing to do with showing a node on a page? We are *long* past "show a node on a page" as the API-defining way that data gets used.

X module introduced Y state years ago. Sure, it's not in core, but Drupal is, and has always been, much more than core. Yes, we're a CMS: That means we're not a Web Publishing Tool that limits itself to thinking in terms of "show object in HTML page". A CMS *is* about data unto itself that gets repurposed in many ways, not just "viewing". (Ask our upcoming DrupalCon Portland keynote speaker Karen McGrane about that.)

fago’s picture

I don't understand why the entity system can't have a notion of entities being 'viewed' and 'edited'. Reality is that the entity system exists in the context of a CMS, where things are being viewed and edited. We even built, and continue to build, a UI on top of the entity system. We don't need to abstract concepts like 'viewing' and 'editing' out of the entity system.

It's not my goal to abstract concepts like "viewing" and "editing" out of the entity systems, we have entity render controllers and entity-form-controllers to support exactly that. But what we do not have is a revision which is used specifically for viewing - or a revision that is used specifically for editing. Thus I see no point in *inventing* the concept of such.

However, what we do have is a revision that is used by default by the entity system - for whatever we'll use it.

Calling it the "viewing revision" is therefore inaccurate.

Exactly - it's inaccurate. That's why I'd prefer "default revision".

EntityInterface currently defines isDefaultRevision(). Do we change that to isViewingRevision() and add an isEditingRevision()?
Introducing isEditingRevision() without having node/x/edit pages using it would be quite confusing not? So no, this issue is about terminology, it should not introduce anything. As long as the entity system does not need to deal with "editing revisions" specifically, I do not see a point for discussing the term as part of "entity revision terminology". I see the point for discussing it in context of e.g. workbench 8.x, but that's workbench's terminology then.

As sun said it:

Remember, this issue is about terminology only. There's nothing (or there shouldn't be anything) that would prevent contrib from introducing new revision terminology on top of the existing (or possibly even, replacing the existing).

In D9, and 2016, the situation might look different. Especially after x.module introduced the new Y revision state. And if that proves to be a common enough use-case, we can certainly extend our core terminology to incorporate it. But there's no reason to "guess" that future upfront.

Exactly - so why should we come up with identifiers for concepts we do not have and consequently do not make use of?

So, here is how I'd see the terminology:

Entity
A data object. Has a unique ID within the keyspace of "Entity Type". (Vis, all nodes nids are in the same keyspace, but separate from user uids.)
Revision
A particular historical variant of an entity. Each has a unique ID within the keyspace of "Entity Type-Revisions". (Vis, all node vids are the same keyspace, but separate from user vids.) That is, the Revision history of a Node is a list of Revisions. (This is no change from now; revisiting this term is punted to a later issue.)
Default revision
The Revision that will be selected if you load an Entity by default; i.e., if you load the entity by entity ID and do not specify a revision ID. node_load($nid); gets back whatever the "default" revision is, which may or may not be the most-recently-edited.
Published
A boolean property/field of an entity that indicates if non-administrative users should have access to the entity - as right now implemented by nodes. The entity system does not implement or take care of the published state of an entity - it is up to the entity type to implement a publishing state (using the entity storage and access systems) or not.

fago’s picture

Issue summary: View changes

Fixed a few more "Version"s.

jhedstrom’s picture

Version: 8.0.x-dev » 9.x-dev
Status: Needs review » Postponed

Marking postponed and moving to 9. I don't think there's anything to be done here for 8.x nearly 2 years later.

Bojhan’s picture

Version: 9.x-dev » 8.0.x-dev
Status: Postponed » Needs review

Actually this can still get done now, this can be a small change (only UI facing terminology change) with little to no disruption.

effulgentsia’s picture

Title: [Policy, No patch] Overhaul the entity revision terminology » [Policy, No patch] Overhaul the entity revision terminology in UI text
Issue tags: +Needs issue summary update

Retitling per #123 for now, but I wonder if the more limited scope should be a new issue instead. If we want to continue it in this issue, I think the issue summary needs an update with concrete information on which UI text changes are being proposed.

Jaesin’s picture

Issue summary: View changes

Editing the description since there was never a consensus reached for the "active" term and it could be easily confused with the default revision.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

webchick’s picture

Version: 8.1.x-dev » 8.2.x-dev

This was talked about in triage in reference to the Workflow initiative, which currently lists this as a "should have" issue. I was asked to chime in with my "product manager" hat.

To me, I would even call this a "could have" as far as the Workflow Initiative goes, at least for now. We've never really explored the revision functionality in usability tests, and until we do get some raw data on whether it is indeed confusing to end users (which would be much easier to test once Content Moderation gets in), I can't see taking a wild stab at what we think might be better terminology, only to possibly need to change it later, based on data.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

smustgrave’s picture

Brought this up in slack and it appears to be a duplicate of https://www.drupal.org/project/drupal/issues/2899719