Rename entity "bundle" to "subtype" in the UI text and help

problem is, those proposals are worse. we actually spent a lot of time on this term in the field api sprint. lets see what folks propose. remember that it has to be substantially better than bundle or else we are breaking backward compat with code and docs and people for little benefit.

I agree that "bundle" confuses the heck out of people. I spent like 15 mins explaining them to people at DrupalCamp Chicago a couple weeks ago.

They aren't "sub-entities" because they're not entities. Edit: Nor under entities. They're above entities in the hierarchy of EntityTerminology.

"Entity subtype" seems more reasonable to me.

I've always liked "Subtype" as for content the entity type is "node" and the subtype is "article". Also, you attach the fields to the entities, not bundles. You configure field instances for bundles, but not attach.

Also see #1374116-5: Move bundle CRUD API out of Field API.

Bundles have been introduced by the field api, and have been moved to the entity api *partly*. The term bundle makes sense for me once you are looking from the field-api storage view, i.e. it bundles certain fields.

However, once we clearly make bundles an entity concept, they'd become more than just a storage thing - and in reality they already are. They are Drupal's notion of an entity subtype.

Thus, +1 for coming up with a term that matches its actual usage.

Related, I could think of mixins (or "entity roles"?) to match Drupal's modular nature very well. See #100925-64: Add "OO" bundle inheritance features. If so, a "bundle" could be seen as a bundle of certain mixins/entity-roles.

Bundles confused the heck out of me until someone suggested I think of them as node types and entity as the node module. Maybe it's just because I've been using nodes for so long, and maybe someone new wouldn't think of it that way, but that analogy helped me immensely. For that, I would "vote" for entity sub-type because it makes that analogy clearer from the start.

Michelle

I'd vote for entity subtype as well :)

Bundles are just one reminder that Field API is older than the Entity concept.
I'm a strong supporter of folding what can be folded into entities (fago's plan), as well as killing the term "bundles'.
"Sub-types" is not the nicest word, but it beats bundles any time of day.

Sub-types is ugly but more easily grokable than 'bundle'.
I remember what really confused me for a long time is than in english a 'bundle' is a grouping of things, which makes it sound rather abstract. Yet in Drupal a bundle is a thing in itself, such as a vocabulary or a node type.

The thing is, we already have 'node type' really deep in our Drupal mindset, while 'entity type' is fairly new. Given a time machine, I'd say we go back and use another word for 'entity type'.

BTW, for 'type', my thesaurus says: kind, sort, variety, class, category, set, genre, species, order, breed, race; style, nature, manner, rank; generation, vintage; stamp, ilk, cast, grain, mold, stripe, brand, flavor.

There's at least a handful of those we've not yet used in Drupal ;)

So yeah, originally the term 'bundle' was strictly Field API oriented. It was coined as a way to refer to "the collection of fields that a given entity has" - i.e as in "a bundle of fields".
Each entity type is free to decide which criteria applies to its own entities - as bjaspan phrased it back then, Field API asks node.module "so, what are your bundles ?", node module thinks "ok, so what are my node types ?", and says "here, dude, here are my 'bundles', as you say"). We didn't want to formalize a notion of 'subtype' on a concept ("entity") that didn't exist by itself yet..

As Entity API and RDF came, the notion of 'bundles' silently and quite naturally shifted from "the lingo Field API uses to communicate with the outside world" to a more general structuring concept for different subsystems to allow for "different flavors of entities within a given entity type" - i.e more as in "a bundle (a family) of entities within a given entity type" : a single property commanding the behaviors in various subsystems (Field API, RDF...).

[edit: this "one criteria to control several behaviors" switch means more coupling and less flexibility, but that is probably more realistic than "each subsystem is controlled by its own dedicated property". Renaming bundles to something else at the Entity API level just means we consciously make that switch that we did unconsciously so far]

The word 'subtype' is indeed a good conceptual helper here - mutually exclusive families within an entity type.
However, I'm afraid it might cause a WTF in practice when applying it to actual code and db schemas within entity types implementations : the "subtype" as an entity is the "type" as a node...
- $node->subtype = $node->type; // Hum...
- when looking at your {node} table in phpMyAdmin, the 'type' column is what holds the subtypes - and that's what you expose for EFQ : "read my 'subtype' property from my 'type' column".

Entities are an abstraction, and the Entity API needs to look at the $entities with some level of abstraction. For the code there, 'entity type and subtype' make sense. But few developers go in there. The code within the implementation of a given entity type shifts one abstraction level, you're coding, say, 'nodes', and these nodes have 'types', not 'subtypes'.

Really not sure about subtypes for this for similar reasons to the ones yched mentions. What we really want is another word for 'type' (i.e., to match node type which unfortunately conflicts with entity type, and we can't use entity-type type). Thesaurus doesn't come up with much either.

Entity-type-type!

I guess the other possibility would be to make bundles "types" and entity types something else. That ship has likely sailed, though.

Edit: @joachim -- Entity type flavors. Yes! I want raspberry. ;)

With the move to "$entity as classed objects", the "entity type" would de facto be pretty similar to (PHP) "class".
Except :
- different capitalization standards : $node->class = 'node'; vs get_class($node) == 'Node';, or 'taxonomy_term' vs 'TaxonomyTerm'
- with "$entity as classed objects", you can still create your own MyCustomNodeClass subclassing Node, with the entity type still being "node". Or we state that actual entity classes (Node, User...) must be "final" (actual business methods live in separate handler classes anyway), in which case entity_type and class are strictly isomorphic...

I still see people referring to Entity Types as Entities, and that was also the first way in which my brain wanted to organize thing when I started working with Entities:
Entity Type = Entity
Bundle = Type
Entity = Instance

Er, I don't think we can go with "Entity" meaning anything else than "an $entity object"...

[edit: let's not bias by the name of the variable - I don't think we can go with "Entity" meaning anything else than "a specific object being a Node or a User or a Comment or a..."]

Maybe an "Entity Item" ?

I don't see any easy name for this however...

I guess the other possibility would be to make bundles "types" and entity types something else. That ship has likely sailed, though.

I thought this while reading the thread, and didn't dare to even type it.

An entity usually means a specific thing, rather than a class of things, so that particular one I'd like to leave as is.

yched's suggestion of:

Entity -> Entity
Entity type -> Entity class
Bundle -> Entity type

Seems pretty good to me actually. The business logic is all going to be handled in controllers, so it would not be impossible to make the entity PHP classes themselves final if we really wanted them to match up exactly (although we might not need to take it that far).

I like this suggestion too and it makes much sense to me as all entities of "class node" would really be $entity instanceof Node (or maybe NodeInterface).

I don't think we have to make the entity class final though, The entity class just remains 'Node' even if a customization module replaces it with CustomizedNode extends Node. That way a node entity would be still an instanceof Node (or NodeInterface).

"Bundle -> Entity type" will be a fun transition to make, both in code and in brains, but I too think the overall proposal in #20 makes sense.

Making the word "type" always refer to the same thing whatever abstraction level you're looking from ("type as an entity" = "type as a node" = "content type" in the UI) looks like a good thing.

+1 as well. It's going to be confusing as all hell for awhile, but I think worth it in the long run.

I love #20.
In the category of "why didn't we think of this before". Much nicer. Grokability++.

I'm sorry to post here as I'm fairly new in Drupal, but I hardly overcame some understanding difficulties, stated in #1330368: Example of how to extend a File entity by attaching a field to it, comment 7 and later.

I found one thing especially confusing: the use of the "type" qualifier when in fact talking about a specific "implementation".
This implies that's this implementation belong to an (computer-representable) concept (as the .object referred to the .class).
But in the Drupal world this is used for concepts where there is no .class; they are totally abstract concepts.
[ in fact there's [kind of] entity.inc.class but it's rather not the most helpful starting point from the learning Drupal developer POV ]

Thus I would rather leave off the term of "type" when possible (especially in the API parameters list) and use the term "machine_name" instead.

Eg: field_access(... $entity_machine_name ...).
Firstly because the data type is a string, but also because the value it represents is as much the entity type as the entity machine name,
The notion of "name" is far less confusing than "type" while much more helpful, as soon as you understand what's an entity as a whole (both definition, loading, ...)
Moreover two entities may have different "machine name" while being totally identical (of course that would be dumb but doable) and "type" often refer to something unique (whose duplication is useless, like int and int2).
Moreover I agree with #20 where entity should not be a class multiple <somethings> as it is often see, by definition, as something abstract.
In fact it's one of the more abstract term available in the dictionary (excepting "concept" and "type").

"name" is a string which reference <something>, "type" is abstract but even more confusing than "entity" as it
does not even give some of the hints "entity" gives about the <something>
From a code-generator POV, Drupal is an application and relies on php code to be run.
I would say that all of int, field, bundle, entity are types (though integer is a primitive type), because all of them are to be represented now or later by php code which will reference them, using the computer-language notion of "type" (or use "struct" for some of them (like bundles) if you want ;))

That being said, the most confusing thing IMHO is about fields and field types (see the above referenced issue).

So what about preferably using "machine name" when possible in the API then explain more deeply to which "type" this "machine name" relates to, outside of the prototype, for a more general understanding of Drupal concepts.
And why not systematically state where the stuff comes from (loaded from database => CRUD, in-code) and how abstract it is related to its parent(s) concept (picture would help).
The fact that you need to call *_create_*() (once) in order to use something is sometimes very helpful (especially for a Drupal beginner)

PS: I actually considered that I may be one (or two ?) conceptual level below yours, (or too new technically), in such a case please ignore ;)

+1 to #20

From #20: (adjusted order for clarity)

Entity type -> Entity class
Bundle -> Entity type
Entity -> Entity

While this might make sense from a programmer/developer's perspective, I don't think it really improves the terminology and meaning for site builders/administrators/users.

Also, one could make the following (somewhat bogus, but still relevant) counter-argument to the stated reasoning/idea for "Entity class":

var_dump(gettype($entity))

Yes, I'm fully aware this returns "object", but please note the function name, and in general, the correlation with "data types".

I mean, I'm not strongly against this proposal, but I believe it's not going to be a huge improvement for people who're not badass-core-developers. ;)

That said:

I found the brainstorming in #11 interesting. Combined with the clarification that entity types primarily differ in their business logic, and that "bundles" are merely sub-representations of the entity type to gain a slightly different UI and optionally also different/additional attached properties/fields/data, but the essential business logic stays the same regardless of bundle, my thinking is generally more along the lines of this:

Entity type -> Entity type
Bundle      -> Entity variant
Entity      -> Entity

Lastly, I think we should design the terminology not necessarily around the current system's capabilities, but rather about its upcoming capabilities:

As with node types in D6, bundles in D7 are still rather "abused" to achieve different behaviors (actually business logic) currently. That's mainly, because it's non-trivial to create a new entity type.

However, with the rise and further evolution of Entity Construction Kit (ECK), I see a very good chance for this to change soon-ish. Mayhaps... even in core.

What I'm after is that we don't run short on efforts to abstract and generalize most of current "content" (node) concepts to make them available for all entity types. In combination with ECK, this means that we'll soon reach a state at which it's no longer necessary to abuse a node type/bundle for something completely different, just because nodes happen to have some more enhanced publishing, revisioning, access, integration, and other features.

Instead, you create a new entity type. Because that is what you actually want.

Bundles or variants will only remain for use-cases in which the concept and business logic is actually identical.

#20 sounds very tempting. My main concern would be if I see a variable $entity_class, should I expect it to be "node", "user", "comment" or the name of a PHP class? Because looking at that I'd half expect it to be the name of an actual, well, class.

Also, I'm interested where this ends up because we may want to rename stuff in the plugin system to align with it, since the concepts are parallel.

Regarding #30, here's a related issue for that: #1400170: Change entity info keys/names from 'taxonomy_term' to 'TaxonomyTerm' (entity class name).

Regarding #28, I feel the "variant" scenario is only okay if we rename node types to node variants as well.

Not to cause too much of a problem, but #1599108: Allow modules to register services and subscriber services (events) is going to be bringing in a concept from Symfony also called "bundles", which we cannot avoid. I think that means we have to come up with a better name for "entity subtype", because otherwise we end up with "bundle" meaning two different things that have nothing to do with each other. :-(

For that reason, bumping to major.

So Death To Bundles, one way or another.

If we want to keep 'node type' because it has years of history behind it, then we to replace 'entity type'. And so for that, we need a term that feels 'bigger' than type.

Using 'class' actually makes a lot of sense now that different (old) types of entities have different PHP classes, thus as in #20:

Entity -> Entity
Entity type -> Entity class
Bundle -> Entity type

The "Entity type / bundle" conceptual pair in D7, even if possibly cryptic at first, has a fairly commonly accepted meaning now. There's a huge amount of code, inline comments, blog posts, online or printed documentation that build on those two expressions.
It's IMO unrealistic to think we can switch one to suddenly mean the other in D8, that would be a major doc mindf***k.

I'd say #28's "Bundle -> variant" is the least intrusive move so far.
@webchick sort of shut the discussion by stating she'd rather stay with 'bundle', but that argument becomes moot if external reasons move "bundle" off the table. So let's reconsider 'variant' ?

I'd like to propose renaming "bundles" to "valences." This would echo the word's meaning in linguistics, where valence or valency describes the number and type of arguments controlled by a verb predicate. For example, some verbs take no arguments, e.g., "It rains," while intransitive verbs take a subject but no object ("He sleeps"), and other verbs may have multiple arguments ("He gave her a flower"). A "valence" is therefore roughly analogous to the thing in Drupal that we are currently calling a "bundle." It defines the number and nature of properties that an entity is supposed to have.

The term "valence" also has the advantage that it is not being used currently in Drupal or in Symfony or in other computer programming contexts. This therefore ensures that there will not be a problem with naming conflicts and makes "valence" preferable to words such as "type" or "class," which are already overloaded with multiple meanings and therefore likely to create confusion. ("Variant" also has some existing meanings in Drupal, so it also has the potential to create confusion.)

I first heard of "valence" as a linguistics concept in college, when a doctoral student hired me to type his dissertation on "Verb Valence Structures of Old Saxon." Some languages other than English have fairly complex valence structures. As Wikipedia explains, "One can therefore compare the verb to a sort of atom with hooks, susceptible to exercising attraction on a greater or lesser number of actants. For these actants, the verb has a greater or lesser number of hooks that maintain the actants as dependents. The number of hooks that a verb has constitutes what we will call the valence of the verb." (The term "actant" in this passage is essentially synonymous with "argument.")

http://en.wikipedia.org/wiki/Valency_(linguistics)

If the only way we can find unused nouns is to dip into words that no one but lingustics Ph.D's have heard before, we've got problems. :-) I'm afraid I couldn't even follow that description well enough to say if it is actually descriptive or not.

The advantage of taking an obscure word (or even an entirely new one) is that it doesn't clash... it's commonly done in maths, for instance.

That said, I'm not sure valence hits the spot. If you've done chemistry (and I'm pretty sure it came up in my GCSE chemistry -- age 15 -- so not terribly advanced or obscure!) you'll know it describes the number of bonds an atom can form. So I don't think that's quite the right direction of meaning. Though of course, if we were to adopt it for Drupal, we'd steer the meaning towards what we want it to be -- much the same way an injection in maths doesn't mean anything to do with needles.

> There's a huge amount of code, inline comments, blog posts, online or printed documentation that build on those two expressions. It's IMO unrealistic to think we can switch one to suddenly mean the other in D8, that would be a major doc mindf***k.

It's one version's-worth of docs, whereas 'node type' is lots more.
The first is wider-reaching, the second is older. I honestly don't know which I think should win!

@Crell: Drupal and software engineering is full of words that fall outside the realm of common vocabulary: node, tuple, codec, intranet, megabyte, daemon, reverse proxy, algorithm, polymorphism, recursion, interface, etc. Most of these terms are familiar to you not because they are common but because you have trained yourself so that this specialized vocabulary now comes naturally to you.

We use specialized terms precisely because they refer to abstract concepts for which there is no simple everyday term and because trying to use common language would create confusion. If we wanted to use more common language, we could say "connection" instead of "interface," or "procedure for doing things" instead of "algorithm." We choose to forego the common language because it would make our communications less precise and less clear. When we use specialized language, we are able to define it just how we want, and we avoid the trap of having people assume they know what the word means when they really don't.

The word "valence" is not so obscure that only linguists use it. It has related meanings in the fields of chemistry, mathematics and psychology.

Anyway, it's just a suggestion.

Am I the only one that saw that and imagined curtains? Yes, the spelling is different but it's close enough that I had to actually go double check they were spelled differently. LOL!

I don't have any facts here, just a gut reaction, and that is that it just sounds weird. I'm cool with lots of Drupalisms and learning new words but I'm really not keen on "valence" for this. Maybe it's because I've never taken chemistry. ;)

Michelle

@Michelle:

Hm, well, is there some other term that can replace the term "bundle" and still carry the meaning of, "collection of elements/field definitions"? The strength of "bundle" is that it carries with it the sense of, "a way of grouping some things." Changing the name to "entity subtype" loses that meaning. I thought "valence" could retain that meaning. "Valence" is similar to the term "arity," which is currently being used in computer science contexts to mean "the number of arguments needed by a function":

http://en.wikipedia.org/wiki/Arity

I agree that "valence" is a rather obscure term. So what are some alternative words that could mean something like "bundle" but won't conflict with other naming conventions already in use? Here are a few possibilities that occurred to me:

• collection, but this term is already being used in various ways, e.g., NodeReferenceCollection
• list, array, schema, package and struct are already heavily used
• component list might work, but the Webform module already uses "component" to mean "an individual form field."
• property list?
• shelf? Here I'm thinking of a shelf as a place where you place and arrange things, such as a bookshelf or kitchen shelf
• drawer? Similar to shelf.
• rack? I'm thinking for example of a wine rack, which is a tool for organizing collections of wine bottles.
• assembly or assemblage? Here I'm thinking of a circuit board, which is a place for putting together an assemblage of electronic components. However, "assembly" evokes the act of putting things together rather than the actual assembled collection, so it doesn't feel right to me.
• construct?

> still carry the meaning of, "collection of elements/field definitions"?

I rather thought we wanted to get away from that... it's only one part of what we now mean by the term 'bundle'.

My impression was that we wanted to convey the idea of subtype... but without saying subtype.

My point was that if you're going to use an obscure word for it that sounds like curtains, you could just as easily call it "curtains" and it wouldn't be any less weird except for the subset of people who actually know what a "valence" is. I don't know what a good word is (I still like subtype but I seem to be the only one) but I don't think "valence" is it.

Michelle

I think the suggestion in #35 is definately the way to go.

Entity -> Entity
Entity type -> Entity class
Bundle -> Entity type

Each "entity class" is described by a PHP class, e.g. File, Node or User (all extending Entity).
"Entity type" makes sense instead of bundle because we already say "Node type".

My impression was that we wanted to convey the idea of subtype... but without saying subtype.

Biology has a multi-level system of subtype names, including "class." Unfortunately the subtype of a class is called "order," which seems likely to be confused with the more common meaning of the word. But next down is "family," which seems like it could work, and avoid the problems associated with re-defining "entity type."

Entity type -> Entity class
Bundle -> Entity family
Entity -> Entity

I really like the direction of @sun's thinking in #28. We need something that will make intuitive sense to site builders, not just programmers.

However, instead of replacing "bundle" with "variant" (his suggestion), what if we tweak it a bit to "variety"?

They mean essentially the same thing, but "variety" is a much more common word which I think makes a huge difference.

There are also some pop culture references that help us out here (not sure about anyone else, but http://en.wikipedia.org/wiki/57_varieties is definitely the first thing that comes to my mind when I hear the word "variety", and I think the analogy works almost perfectly), and if you like the biology reference idea that works well too (http://en.wikipedia.org/wiki/Variety_%28botany%29).

So basically, in Drupal we would have different entity types, and each type of entity can have different varieties.

What about "abstract entity type" and "entity type"?

Or "base type" and "type"?

+1 for varieties. makes it easy for site builders to grasp IMO :)

If nothing else, I think discussion has helped me personally to better understand the problems with the term "bundle." I think "bundle" was chosen originally with an intention that it would convey something about the defined characteristics of an entity subtype -- namely, its field definitions and other properties. However, it has become clear that in fact it refers to the "subtype" of an entity type, where entity types can be "node" or "taxonomy" or "comment," etc. Thus, a "node bundle" is the equivalent of a Drupal 6 "content type" -- a subtype of nodes.

Following this logic, therefore, the suggestion in #35 makes a lot of sense:

Entity -> Entity
Entity type -> Entity class
Bundle -> Entity type

However, I still have some misgivings about this. Maybe I'm off base, but I thought I should at least make my points.

(1) A "bundle" is a subtype/subclass of the concept we are currently calling an "entity type," but it isn't self-evident just from the terminology that a "type" is a subtype of "class," so renaming along the lines suggested above will really not make that subordination clear. If not for the points made in comment #12 about table naming conventions, therefore, we would be better off with the following:

Entity -> Entity
Entity type -> Entity type
Bundle -> Entity subtype

(2) I'm also not convinced that "bundle" ONLY refers to categorization within entity types. It feels to me like the concept of "bundle" is actually doing double duty by referring to two separate meanings:

Meaning #1: A bundle is a subtype of an entity type. If the entity type is "node," then we can have subtypes (currently named bundles) such as "event," "blog post," "article" or "page." By assigning subtypes to nodes and other entities, we are simply making a statement about how we intend them to be used and listed on the website. Each subtype of "node" may have different field definitions, etc., but this isn't necessarily always the case. For example, an "event" will likely have date and location fields that differentiate it structurally from the other node types, but "article" and "page" may actually be structurally identical to each other. The only reason we have different node types for "article" and "page" is so that we can tell content creators to treat them and use them differently. In meaning #1, therefore, "bundle" is kind of like a taxonomy term. It's just a classification.

Meaning #2: A bundle is a set of specifications which pertain to a subtype of an entity type. In this second meaning of the term, "bundle" does refer to the field definitions and some other characteristics of the entity subtype. I think the term "bundle" was originally chosen with the expectation that it would convey this idea. In other words, the "bundle" for an "event" node would be the bundle of characteristics which tell us that it contains a bundle of attributes including a date field, a location field, is published but not promoted to the front page by default, etc. This is the meaning that led me previously to propose renaming a bundle as a "valence."

Reading this discussion has helped me understand the important of renaming "bundle" so it carries meaning #1, but do we really want to strip the word entirely of meaning #2? Calling it an "entity type" (or even an "entity subtype") entirely removes meaning #2.

How about something such as the following?

Entity -> Entity
Entity type -> Entity class
Bundle -> Entity type definition

"Entity type definition" is somewhat verbose, but it would communicate both meanings #1 and #2.

Needs issue summary

Updated issue summary.

Added issue summary.

Adding issue summary

Variant still makes sense to me, even after reading more recent comments and having discussions after #28.

@David_Rothstein's suggestion of Varieties in #28 is essentially the same, I think. However, I have to amend that I never heard of that term/word as a non-native speaker before. Looking up German translations for variety, it actually seems like the meaning of "variety" implies/enforces plurality, but I don't think that's proper within the context of "entity variety" — within that context, we actually mean "entity variant." (whereas "variant" == a single incarnation of the variety, if I get it right)

Regarding @webchick's fear in #33, I don't have or see any problems with changing the Node API terminology. That's long overdue anyway, and the misleading "node type" != "entity type" mismatch essentially is one of the primary problems of our terminology in the first place.

> Looking up German translations for variety, it actually seems like the meaning of "variety" implies/enforces plurality

No, you can have a single variety of something as well as the plural meaning. The OS X dictionary says:

• a thing that differs in some way from others of the same general class or sort; a type : fifty varieties of fresh and frozen pasta.

Having said that, 'variant' sounds better to me than 'variety'.

I must say I like

Entity type -> Entity type
Bundle      -> Entity variant
Entity      -> Entity

Term variant makes sense as well, while term bundle just doesn't. Still, we want to keep referring to a term's vocabulary not to a term's variant, right? The same way I don't see the requirement to rename node types to node variants although it would be nicer and more consistent. But that doesn't stop us from renaming entity bundle to entity variant imho.

Still, we want to keep referring to a term's vocabulary not to a term's variant, right ?

Agreed. 'variants' is the generic term used by Entity API and modules that want to provide functionnality across entity types. Internally, a given entity type can use the naming that makes sense within the specific business logic at hand. The example we used to explain 'bundles' in D7 remains valid IMO :
- The entity API asks for the list of 'variants' for the taxonomy_term entity type
- taxonomy.module goes "ok, so what are my vocabularies ?", and turns back to entity API saying "here, here are what you call my 'variants'".

Just an FYI: CTools uses "variant" so there's a precedent for the term in the Drupal word.

Michelle

> Internally, a given entity type can use the naming that makes sense within the specific business logic at hand.

Agreed.

> The same way I don't see the requirement to rename node types

But then we have the word 'types' meaning two different things and they're in close proximity, eg: 'node 5's entity type is node and its node type is page'.

> Just an FYI: CTools uses "variant" so there's a precedent for the term in the Drupal word.

Oh and if I understand correctly, in CTools it means a different presentation of the same thing, such as a panel. Hmm...

But then we have the word 'types' meaning two different things and they're in close proximity, eg: 'node 5's entity type is node and its node type is page'.

Yes. Renaming it would be better, but regardless from that variant is better than bundle.

> Just an FYI: CTools uses "variant" so there's a precedent for the term in the Drupal word.

Yes, you can create different page variants in panels/page manager. Still, "variant" is generic concept what can be applied to anything, so I don't think that the likelihood for people confusing page variants with entity variants is very high.

I like Variant but like Fago mentioned, it would be weird to refer to taxonomy terms of a certain variant (as opposed to the current vocabulary).

That said, internally this makes sense.

However, I think it might be beneficial to maintain some of the current language on the UI level, namely:

- Content Types
- Taxonomy Vocabularies

Oh and as far as Panels goes, I wouldn't worry about that. They already have "Contexts" which are different from the Context module's contexts, so its confusing anyway :)

I wasn't thinking anyone would be confused. I was just pointing out that it's not a totally foreign term in the Drupal ecosystem. :)

Michelle

I like the word Variant for Panels/PageManager, where the differences between variants are strictly display oriented, but I'm not so sure about it for entities, where the differences are structural (if you consider fields as part of entity structure, which I do).

Within .NET, an "entity type" is "the fundamental building block for describing the structure of data", and I think other systems might also follow this idea/definition. The challenge is, in Drupal we have two levels at which entity data is structured: a level at which code adds some base properties (nodes have titles, users have names and email addresses, files have URIs, taxonomy terms have names and descriptions), and a level at which administrators add fields.

.NET has a concept of type inheritance, and uses the terms "derived type" and "base type" when "type" alone is too ambiguous, but in Drupal, we (so far) only have the two levels, not an arbitrarily deep inheritance tree.

Therefore, I suggest either:

Entity type -> Entity type
Bundle -> Entity subtype

Or:

Entity type -> Entity base type
Bundle -> Entity type

I'll also point out that MIME types, which are also 2 level, use the terms "type" and "subtype": http://en.wikipedia.org/wiki/Internet_media_type, http://www.iana.org/assignments/media-types/index.html.

So the only objections I see to subtype in the above comments are:

#12:

However, I'm afraid it might cause a WTF in practice when applying it to actual code and db schemas within entity types implementations : the "subtype" as an entity is the "type" as a node...

I don't see this as a problem. $node->bundle does not exist in any code in HEAD (and shouldn't, since if you know you're dealing with a node, then you're not dealing with it as a generic entity). We do have calls to $entity->bundle(), which I presume would be renamed to $entity->entitySubType(), and I think that's perfectly clear. Perhaps the one confusing thing we'd have is the Node class's bundle() method would become:

public function entitySubType() {
  return $this->type;
}

But that's 1 place in our codebase, and we can comment it.

For db queries, we'd have stuff like SELECT * FROM {node} n INNER JOIN {field_data_body} f ON n.type = f.entity_subtype, but only within your query logs, not in the codebase, since you should never write queries like that, but only use EntityFieldQuery, so I don't see this as a big deal either.

#50:

Meaning #2: A bundle is a set of specifications which pertain to a subtype of an entity type...Calling it an "entity type" (or even an "entity subtype") entirely removes meaning #2.

We're not currently very consistent between distinguishing a type as a string from configuration information about that type. For example, node_permissions_get_configured_types() calls node_type_get_types() to get the types' configuration and assigns that configuration to a local variable $type, whereas in other places, we would call that $type_info. It would be nice to clean stuff like that up a bit, but in a separate issue. I think we can solve the problem of distinguishing types and subtypes as string identifiers from their configuration info.

Looking at phpcr, it has a type-inheritance model - see e.g. here. You get a single type for an entity, which may inherited (ala node.article extends node).

I don't think we want to go that far, but still having the same terminology in place would be a plus for me.

Entity type -> Entity type
Bundle -> Entity subtype

I can definitely see the advantage of this is that it's easier to grasp. There's entities which have different types, and each type (eg node) has a sub-type (eg article).

But then we absolutely have to change 'node type'!

"node is an entity type. Hence, the node type is an entity subtype"
Easier to explain than "bundle".

Easier, but still has potential for confusion and tongue-twisting.

Updated issue summary.

I updated issue summary i.e. included (sub)type suggestion.

If I understand correctly, this is the real life example:

Entity type -> Entity type e.g. Node
Bundle      -> Entity subtype e.g. Node type e.g. Article or Event
Entity      -> Entity

+1 for this combination.
Also, I found more logic in this order from my personal non-native English speaker / non-core developer / site builder perspective:

Entity      -> Entity
Entity type -> Entity type
Bundle      -> Entity subtype

"subtype" vs. "variant" sound both fine to me, can go either way.

The only issue I can see with "subtype" is that it is going to be strange to translate. Compared to the universal term "variant", "subtype" is also very technical, so I'd be a bit hesitant to put that into user-facing interface text.

But anyway, both would work for me.

@sun: I like word subtype because among other things it's consistent with word type - you just add prefix. I don't know about other languages, but in Croatian this is also true:

   Type ->    Vrsta
Subtype -> Podvrsta

Lot easier to explain/translate.

"subtype" is also very technical, so I'd be a bit hesitant to put that into user-facing interface text

I did a search on http://localize.drupal.org/translate/languages/test/translate?project=dr... (that link might require that you're a member of the test group on localize.drupal.org) and found the following 4 user-facing strings in Drupal 7.15 with the word "bundle":

- Missing bundle property on entity of type @entity_type.
- Attempt to create an instance of field @field_name without a bundle.
- Attempt to create an instance of field @field_name on bundle @bundle that already has an instance of that field.
- Attempt to update an instance of field @field on bundle @bundle that doesn't exist.

I also think the word "entity" is generally too technical for user-facing text, so I searched that too. Here's where it currently appears in Drupal 7.15:

- Missing bundle property on entity of type @entity_type.
- For this query an entity type must be specified.
- Entity %entity has no base table.
- Attempt to create field name %name which is reserved by entity type %type.
- Attempt to create an instance of field @field_name without an entity type.
- Attempt to create an instance of field @field_name on forbidden entity type @entity_type.
- The Field module allows custom data fields to be defined for entity types (entities include content items, comments, user accounts, and taxonomy terms). The Field module takes care of storing, loading, editing, and rendering field data. Most users will not interact with the Field module directly, but will instead use the Field UI module user interface. Module developers can use the Field API to make new entity types "fieldable" and thus allow fields to be attached to them. For more information, see the online handbook entry for Field module.
- Overview of fields on all entity types.

variant and subtype are both fine from my POV. I don't know how well either one translates, but to my core-developer-brain I can work with either one.

What ctools/Panels currently calls a "variant" will, I think, go away in Drupal 8 (at least the current model we're building doesn't use it yet), so I don't think there should be any intra-version confusion there.

Might "instances" become the item of an Entity Subtype with unique data and a sequential id? These seem to currently be called entities, as well as the more codified Entities.

Edit: "Instance of a bundle" appears to be the accurate term, so it may be my personal confusion understanding the uses of Entity, or this is a reuse that others may have also come across which is an additional term that could use clarification. Or, if there was a shorter term that could be used, that could be useful.

Quoting from http://en.wikipedia.org/wiki/Entity-relationship_model :

Although the term entity is the one most commonly used, following Chen we should really distinguish between an entity and an entity-type. An entity-type is a category. An entity, strictly speaking, is an instance of a given entity-type. There are usually many instances of an entity-type. Because the term entity-type is somewhat cumbersome, most people tend to use the term entity as a synonym for this term.

In other words, by the definition above, "node" and "article" are entity types (with "article" being the more specific type which in Drupal we currently call "bundle", but in this issue seem close to converging on "subtype"), and "node 1" is an entity.

What Drupal's FieldAPI currently calls an instance is something else, and we should rename it to something better, but let's leave that to another issue.

I'd like to see $entity->subType() against bundle() anyway we need to get rid of this before release.
Also new upcoming wtf with behavior #1803064: Horizontal extensibility of Fields: introduce the concept of behavior plugins

Let's finish the debate and rename to subtype, seems people are fine with that, more intuitive than variant. And this must be done with the date people eyeing intl which will add another bundle to the confusion: http://php.net/manual/en/class.resourcebundle.php

Let's also make this issue specific and open other issues for other entity system renames.

If only for the record, I think in our case sub-type doesn't really make sense. If we had the situation, where the "sub-type" is actually an entity type of it's own, then we should totally go for "sub-type". I.e. if we had:

// This is an entity type.
class Node {}

// This is also an entity type, it just happens to be *below* another type in the class hierarchy, so we call it a sub-type.
class Page extends Node {}

That is what is done in generic ERMs and for them "sub-type" totally makes sense.

We don't really have that situation, though. Our current "entity bundles", are really the same entity type (they all have the class Node), just with a bit of different configuration (i.e. default settings, fields, etc.), which is exactly what is depicted by the word "variant". So in our case "variant" is a better choice, IMO.

Just wanted to put that out there. Unless I've just magically convinced a bunch of people :-), please proceed with the rename to "sub-type".

Our current "entity bundles", are really the same entity type (they all have the class Node), just with a bit of different configuration (i.e. default settings, fields, etc.),

I disagree that just because Article and Page use the same PHP class Node, that they shouldn't be considered subtypes. If they have different fields, than from an ERM perspective, they are different. Some ERM systems require programmers to map different data structures to different PHP classes, whereas Drupal has a whole Field API in order to not have to do that, allowing new subtypes to be created via UI. Whether you implement ERM in classic OO or with a Field API / UI doesn't change the concept of different data structure = different (sub)type.

There hasn't been any discussion here for awhile. Is there agreement on an approach?

What about:

Entity type -> Entity type
Bundle -> Entity schema

This would echo (appropriately, I think) the way the term "schema" is used on http://schema.org and would also capture to some extent both the meaning implied by the current word "bundle" and the meaning implied by the proposed words "type" or "subtype." According to WIkipedia, "schema" comes from a Greek work that means "shape" or "plan." I think "bundle" in its originally-intended sense of "list of fields" referred to the morphology of the entity, i.e., its "shape," whereas the terms "type" or "subtype" that are now being proposed actually refer to the intended purpose of the entity, i.e., its "plan." For example, when we say that one content type is an "article" and another is a "page," what we're really saying is a statement about how we intend to use those two content types differently. An "article" anda "page" may have the exact same field definitions, but the site builder intends to use them to present different types of information.

The concept we are currently labeling as a "bundle" therefore encompasses both a list of its properties and a categorization statement regarding its purpose. Switching from "bundle" to "type" or "subtype" captures the categorization purpose which "bundle" misses, but it loses the "list of properties" purpose that was captured by "bundle." Maybe "schema" captures both?

Is there agreement on an approach?

There was no disagreement with "subtype" in the 7 weeks since I changed the issue title in #80 (other than #81 which specifically said to not hold the issue up on it), and that title change was based on what appeared to be a fairly strong majority in previous comments, so I feel it's roughly agreed, and just awaiting someone to implement.

Switching from "bundle" to "type" or "subtype" captures the categorization purpose which "bundle" misses, but it loses the "list of properties" purpose that was captured by "bundle."

That's interesting feedback. Just my 2 cents: In ERM theory, "type" refers to both shape and plan (or for architecture enthusiasts, form follows function). And in Drupal, entity types have both of those aspects (comments serve a different purpose than nodes and therefore, also have different base properties). And bundles are a further refinement of both shape and plan, so I think subtype captures that.

To be clear, I'm not opposed to subtype. I just noticed that this thread hasn't seen any movement in awhile and thought I'd throw in a comment. If subtype has majority support, I'm fine with it. My "schema" suggestion was only intended as an alternative if we _don't_ have agreement on "subtype."

It's major because changing it implies an API change that is going to ripple through large swaths of Drupal. Also because "we're setting ourselves up to confuse every single person who touches Drupal for no good reason" ought to be treated as major. :-)

It looks like we have consensus on the direction, now we need someone to PM and schedule implementing it.

I think we only have consensus among those that would like to see it changed. I've not yet commented here, but I've been following it from the beginning and think that there's no real need to change it.

Symfony bundles are code-only, and creating content types (the most common entity bundle) is from the UI. If you know enough to use hook_entity_info_alter(), chances are you know the difference.

IMO, all we'll do is confuse everyone who has used D7.

Tim: Then you get to document what a bundle class is and why you can't make new bundles by creating a class, but your module needs a bundle class that doesn't define bundles. Just reading that sentence myself I'm already confused. :-)

I'm +1 to changing entity bundle to subtype, but if for whatever reason we don't manage to do it, I don't really see a problem with then renaming [Module]Bundle classes to something else. The word bundle there is just as meaningless as it is in Entity API: just cause Symfony uses the word "bundle" to mean what Drupal calls a module, doesn't require Drupal to stick a Bundle suffix on that class. We'd still have the word "bundle" within some of the methods on DrupalKernel, but really, if you're mucking with DrupalKernel, you're presumed to have a deep understanding of both Drupal and Symfony concepts already.

Let's move on with "subtype". Marking RTBC to increase awareness.

It is perfectly possible that subtypes will actually work along the lines of #81 in D9 or D10 (see also #1838676: Support dynamic entity type management), so I think the term does not only work with the current architecture, but may very well be future-proof, too.

+1 to go with subtypes, that's way easier to explain and understand than "bundle". Developers know subtype relationships, but not entity bundles.

I'm fine with subtype.

(I'd also be OK with leaving it as-is for 8.x and letting people deal with the confusion (not sure this is really worse than node type vs. entity type) in case we don't actually get to it).

Leaving RTBC for a bit longer.

+1 for subtype, I never got the term "bundle" for entity sub types.

I know I should not even write this, but subtype sounds a bit lame because it conceptually opens the door for type hierarchy (subsubtype?) and right now we are stuck with just one level :)

Imagine a world where you can have an arbitrary number of hierarchy levels, each one with its field instance set, lovely :D

@plach, you're talking about http://drupal.org/project/entity_bundle_plugin and what I tried to do for D8 core in this patch, but it was shot down. I'm not giving up though and will try other approaches soon :)

In the meantime, +1 for subtypes from me as well.

Imagine a world where you can have an arbitrary number of hierarchy levels, each one with its field instance set, lovely :D

Exactly. I think this should be the direction we are heading to. Even if it does not work in d8, it's good to have a fitting terminology for later. In practice, that kind of of type-relationships would be often quite useful... Still, modules could at least mimic the behaviour on the field level in d8 contrib.

@amateescu:

Interesting patch, but I think you linked the wrong issue :)

@plach: Nope, it's the right issue. The patch was never posted in one of the "reinvent bundles" issues because of the pushback it received..

Wow, this is really "shooting down"

Speaking of shooting down, I think it's fair to assume a broad community agreement has been reached here by now.

This issue is actually not supposed to transition to fixed. As @Crell already mentioned, the actual work only starts at #100+ :P ;) Hey, at least it didn't take 300! ;)

That said, I already tried to start to change my language in other issues from bundle to subtype, but refrained from doing so in the end, since most bundle stuff that we're talking about these days is referring to a (badly needed) "Bundle API", and each time I tried to replace it, the messaging and communication about a thing called "Subtype API" sounded... strange. ;) You know, that lacks a touch of a proper noun... But perhaps we just need to get used to it — oh, habits.

Anyway. Let's move on to the actual tasks: AFAICS, it would start with these seds + git mvs:

/bundle/subtype/g
/Bundle/Subtype/g

Perhaps we should just whip that up as a quick + dirty patch and see what breaks?

+1 to #101.

Bumping to major. At least two people just got confused in one Twitter conversation about which bundle we were talking about, and one of them was eaton. :-) Leaving the double naming here is a training disaster waiting to happen.

Tagging "Novice":

Replace all occurrences of

/bundle/subtype/g
/Bundle/Subtype/g

but only in the entity context.

Restoring tags ...

I was curious and did a word count. Not really sure which number is the correct one; probably the first one because it relates to entities and not the symfony bundle:

% grep -R 'bundle' core/modules/entity* | wc -l
96

% grep -R 'bundle' core/modules | wc -l
1969

% grep -R 'bundle' core | wc -l 
2305

First stab at this task.

re: #93, is the average module developer going to see any Symfony bundles when interacting with Drupal apis? If not, I'd suggest leaving this unchanged for D8 since I think another big terminology change is worse than occasional confusion.

The patch failed during the upgrade path tests, but succeeded elsewhere.

There will need to be some additional work around upgrading d7 installations to d8 and converting bundles to subtypes.

pwolanin: Yes, any Drupal module developer that wants to expose a service, register an event, or in any way put stuff into the DIC will be writing a (Symfony) Bundle class.

I'm happy to continue working on this, and can implement the entity upgrade path, if we think this issue is likely to get pushed into core. How decided is this issue?

it was RTBC in #91 so i think that means, we came to an agreement..we just need the patch now^^

Ok, I'll make a start on the upgrade path then.

I've added the upgrade path for this and fixed a few minor bugs with the previous patch.

Opened #1939660: Use YAML as the primary means for service registration.

Missed converting some of the tests to use for subtype instead of bundle.

Made the field upgrade path more robust.

Removed reference to mb_strtr().

Looks prety good to me. Probably needs an avoid commit conflict tag :)

-function field_bundle_settings($entity_type, $bundle, $settings = NULL) {
+function field_subtype_settings($entity_type, $subtype, $settings = NULL) {

That looks like it might be confusing... "Subtype" of what exactly? Do these kinds of things need to become field_entity_subtype_settings() instead?

We probably shouldn't rename those instances like field_bundle_settings that have a field context? I still do consider field bundles to be something valid and that they are loaded by an entity type and subtype.

seems like this should be postponed in favor of:
#1939660: Use YAML as the primary means for service registration

@David_Rothstein, @Dave Reid - What about field_instance_settings() to avoid any further bundle/subtype confusion?

Can I also suggest renaming field_attach_create_subtype(), field_attach_rename_subtype() and field_attach_delete_subtype() to field_attach_create_instance() etc. for consistency and to promote the ideal of an arbitrary number of subtype tiers?

Edit: This doesn't make sense, feel free to ignore.

Rebased patch and renamed field_subtype_settings() to field_instance_settings().

@webchick - the issue summary has the conflict with Symfony as the major motivation for this.

Are we going to rename Node? Entity? Breaking documentation and changing central terminology between versions is, to me, *more* confusing and more of an impediment than staying with a term that has become understand to everyone developing for Drupal 7.

field_instance_settings() is misleading, because I would naturally assume that returns me the settings for a specific field's instance. It's not, it's returning an array of settings related to a 'bundle' of fields that are assigned to a specific entity type and subtype. I still think this is too far.

@Dave Reid - Having looked at this closer I agree that instance is the wrong term; these are the settings for a collection of field instances relating to a particular entity/subtype.

I can revert it to field_bundle_settings() but I still think it could lead to some confusion if we're removing all other (non-Symphony) 'bundle' references.

I like either field_group_settings() or field_collection_settings() but these could clash with field_group or field_collection modules.

I'm open to a consensus on this.

@pwolanin - I read the issue summary as saying that the major motivation for this is that "The term bundle is confusing to users and no longer is descriptive of the way bundles are used." The conflict with Symfony is just another consideration.

The question of whether and what to rename bundles has already gone through a lot of discussion. In my view, the discussion has reached a stage at which a decision has already been made with general consensus. I also don't think it's true that "bundle" has become understood to everyone developing for Drupal 7. Just speaking personally, I didn't really understand what the term meant or how it functioned until I read through some of this thread in which the reasons for wanting to rename it were discussed.

FYI, we need to kill field_bundle_settings anyway in terms of CMI conversion. Since the instance settings have now moved to the entity display already, the settings for extra fields have already been merged in there. The same will happen at some point for the form settings (but don't ask me yet how it will be named). The information of whether a view mode is enabled or not, we don't know for sure yet where that will live.

So for now, just leave the name, we'll kill it later.

Just rename it to field_entity_subtype_settings() for now, just in case the CMI conversion doesn't make it. (These things happen...)

There's basically no option to not make it happen, please leave it as is for now, we have a lot of horrible merging anyway all the time working on the field api cmi patch - and I can't even imagine how this is going to affect our current patch :(

Reverted field_instance_settings() to field_bundle_settings() and fixed test failure from previous merge.

The current terminology is pretty bad indeed, and I'm supportive to change this in Drupal 8. Personally, of the 3 proposals, I like the proposal with 'entity subtype' best. Let's get it done! :)

Ok, so field_entity_subtype_settings() in the interim?

No, the scope here should limiting the rename of bundle as in the concept of 'this is an entity subtype, e.g. a node type, a vocabulary, etc.', not bundle in the concept of 'a bundle of fields attached to a combination of entity type and subtype'. Renaming field_bundle_settings() is out of scope and is just an unnecessary change at this point.

#146 already restores the function name as field_bundle_settings(). If we agree with #150, then we should also restore the following function names:

- hook_field_attach_create_bundle
- hook_field_attach_rename_bundle
- hook_field_attach_delete_bundle
- field_attach_create_bundle
- field_attach_rename_bundle
- field_attach_delete_bundle
- field_extract_bundle
- field_test_create_bundle
- field_test_rename_bundle
- field_test_delete_bundle
- field_ui_bundle_admin_path

I think in the long run, we'll want to get these to incorporate the subtype terminology, but I think it makes sense to defer that to a separate issue, because I think to do it right, we'll need to fix more than just the function names.

Note that I just think we should restore the function names, but leave the $bundle parameter name converted to $subtype as already in the latest patch.

However, anywhere we have $entity_type, $subtype as parameters to the same function, I think we should change it to $entity_type, $entity_subtype. Possibly, we should globally change all $subtype to $entity_subtype, and then look on a case by case basis (here or in follow ups) if there's anywhere where the shorter $subtype would be better.

The patch in #153 is a fixed and rebased version of the patch in #146.

@effulgentsia - why should the bundle be the same as the subtype? that's just a typical mapping. If you are going to keep bundle settings, bundle attach, etc they should properly only know about "bundles" and be independent of entity type or subtypes.

If we're not doing a straight rename, then I'm confused.

@pwolanin, if you're implying that subtypes are somehow different from bundles, then what is a subtype?

I was skeptical of that idea originally too and assumed this issue would require a complete rename, but the more I think about it the more it makes sense to me. Consider a sentence like this:

"Each entity subtype has a separate bundle of fields attached to it."

I think it's hard to rewrite that to only use "subtype" (just like it's hard to rewrite it to only use "bundle" today). They actually are two different concepts.

Exactly. They are two different things.

subtype = the sub-type of the entity, in other words, the actual node type, vocabulary object/name
bundle = the array of fields that are attached to a specific entity and it's subtype

That's a fine distinction, but it doesn't mean that a subtype isn't just the name the Entity API uses to describe the thing the Field API calls a bundle.

The one place this makes sense: we have a short list of exposed subtypes, and those without them (like user), still have a bundle for attaching fields.

So, an entity type can have 1-N bundles, and 0-N subtypes, and when the number of subtypes is non-zero, the number of subtypes is equal to the number of bundles...

No strong opinion on my side, but keeping the distinction is fine by me.

I guess we'll be hitting cases where the distinction between the two might a bit delicate to decide ("are we talking about a bundle or a subtype here ?"), but globally it makes sense.

In the light of the (mythical & still totally pipe-dreamesque) feature of "add an extra image field only on node 12", might even be a more future-proof approach. Like, the collection ("bundle") of fields on an entity is currently strictly determined by the entity subtype, but this doesn't strictly have to be a tight coupling.

@effulgentsia - field_test_create_bundle() etc. are used to create or edit entity subtypes for the 'test_entity' entity during testing. They do also add a field collection ("bundle") for the new subtype, but leaving it as field_test_create_subtype() makes sense to me.

@webchick - I'm happy to put some effort into this. In a separate issue...

"Each entity subtype has a separate bundle of fields attached to it."

For none native english speaking the much understable to use already used term Bag in TipsBag and DisplayBag that introduced in D8:
"Each entity subtype has a set\bag (\Countable) of field plugins attached to it."

I like the "set" terminology, as in field_attach_create_set() or field_attach_create_field_set().

"Each entity subtype has a set\bag (\Countable) of field plugins attached to it."
Fields / instances won't be plugins. They will be ConfigEntities, with an associated field_type handler object, that is a Plugin.

So the problem with "collection" is it kind of clashes with http://drupal.org/project/field_collection
"field_set" has infortunate semantic clashes with "fieldsets", and just "set" is ambiguous with the verb.
Not too fond of "bag"...

I'm happy for someone to open an issue to rename $bundles within Field API, but I won't be able to spend time on this before more pressing issues are solved (CMI, field types as plugins...)

Please lets not make changes that are purely offhanded. Bundle was chosen after thought by Yched and others. Just leave it alone if it's not broken.

subtype *Is* in fact a different thing and so making that distinction clear is really correcting a bit of a mistake in D7.

... I am horribly confused now. Can "a list of N fields with configuration" exist on its own independent of an entity subtype? The last time I looked, it couldn't that I understood. When did it become its own thing?

To #159, Entity types with 0 subtypes is a design flaw to begin with. There should always be at least one subtype. User entity's subtype is called, er, "user". Nothing wrong with that. Forcing a special 0-case was a bad idea in the first place and is still a bad idea today.

... I am horribly confused now. Can "a list of N fields with configuration" exist on its own independent of an entity subtype? The last time I looked, it couldn't that I understood. When did it become its own thing?

Me as well. I'm not sure why we need to differentiate at all. We have entities of a certain type to which we have certain fields attached. The entity type determines which fields.

So, then we have sub-types extending its parent 'entity type' with any number of additional fields.

The current proposal for #1868004: Improve the TypedData API usage of EntityNG would be to register the following general (=typed data) types:
- entity
- entity.ENTITY_TYPE (e.g. entity.node, entity.user)
- entity.ENTITY_TYPE.BUNDLE (e.g. entity.node.article)

Imho, this would be inline with the proposal of "bundle" becoming "subtype".
Maybe, we could even just that $type (opt. minus the entity prefix) as basis for field API configuration?

To #159, Entity types with 0 subtypes is a design flaw to begin with. There should always be at least one subtype. User entity's subtype is called, er, "user". Nothing wrong with that. Forcing a special 0-case was a bad idea in the first place and is still a bad idea today.

So "user" is a subtype of "user"? Nope, I don't think it really is. It's just our convenient way to have a $type/bundle name to use. From a usual type hierarchy perspective "user" being a sub-type of "user" is just confusing. I'd much rather say this entity has no-subtype.

@Crell: I think it is possible to imagine "a list of N fields with configuration" existing on its own independent of an entity subtype. However, discussing that possibility is really outside the scope of this issue ticket.

Example: Some people here have expressed a desire for fields to themselves be fieldable. If someday that gets implemented, I can imagine a "field type => field subtypes" distinction in Drupal similar to what we're talking about now with "entity type => entity subtypes." In this hypothetical future version of Drupal, "field subtypes" would each be able to have their own "list of N fields with configuration." These "lists of N fields with configuration" would therefore be independent of entity subtypes (but dependent on field subtypes).

I'm not advocating for that, and I have no opinion on whether it would be a good thing to do. I'm not proposing that we try to implement this or even discuss implementing it. I mention it only to point out that having subtypes or being fieldable is not irrevocably tied only to "entities." Also, there is at least a conceptual difference between (1) being a "subtype" and (2) "having a list of N fields with configuration."

FWIW, I agree that entity types with 0 subtypes is a design flaw.

I'm not asking what it's possible to imagine. I'm asking what concepts our APIs are build on now. If fields become fieldable, then the entire concept of entities and fields breaks down and we're dealing with a completely new API model that is completely different from what we have now. For Drupal 8, as far as I know and as far as fago knows, it sounds like, "entity subtype" and "collection of configured field instances" are semantically the same thing. Splitting the terminology "just in case we may change that in some later version that radically rethinks the architecture" is asking for trouble.

As for single-subtype entities, "one is a special case of many". If you have to think about "is this a subtyped entity or not" rather than just iterating over a list of one subtype and possibly collapsing the list if there's only one, then you have a design flaw.

Crell, I agree with everything you said except that I don't think "'entity subtype' and 'collection of configured field instances' are semantically the same thing." There is a semantic difference. For example, the "article" and "page" content types that are commonly created in a new Drupal instance are separate node subtypes/bundles, even though they are identical in terms of their "collections of configured field instances." They may be used for different purposes on the site, which is itself a semantic difference. There may also be differences in configuration between them. For example, pages might be configured to disallow comments and hide the node's author, while articles allow comments and display the author.

Sheldon: That may be how you visualize it, but at the code/API level it's not true. Page and Article have different fields configured. The body field is shared between them, but Article also has an image field and taxonomy ref.

My point is that if there is no way in the system/API to define a set of fields independently of an entity subtype (which is true as far as I know and sounds like fago agrees), then giving "set of fields" a name independent of an entity subtype only creates more confusion and encourages people to form incorrect mental models. That does them harm rather than clarifying anything.

> FWIW, I agree that entity types with 0 subtypes is a design flaw.

At least on D7, entity_get_info() fills in a single bundle with the same name as the entity type, for an entity type with no bundles at all and no 'bundle' entity key given:

        // If no bundle key is provided, assume a single bundle, named after
        // the entity type.
        if (empty($entity_info[$name]['entity keys']['bundle']) && empty($entity_info[$name]['bundles'])) {
          $entity_info[$name]['bundles'] = array($name => array('label' => $entity_info[$name]['label']));
        }

On D8, I can't fathom where entity_get_info() is diving into the plugin system, so I have no idea...

My point is that if there is no way in the system/API to define a set of fields independently of an entity subtype (which is true as far as I know and sounds like fago agrees), then giving "set of fields" a name independent of an entity subtype only creates more confusion and encourages people to form incorrect mental models. That does them harm rather than clarifying anything.

Yep, I agree. We do not have that right now, so *adding* that as part of a re-name does not make sense.

As for single-subtype entities, "one is a special case of many". If you have to think about "is this a subtyped entity or not" rather than just iterating over a list of one subtype and possibly collapsing the list if there's only one, then you have a design flaw.

I don't see why this should be a design flaw. It's a design flaw if I have to special case on a single subtype that appears to be called the same way as the entity type in order to know whether subtypes need to dealt with. For example, consider you want to show a sub-type select box but only if necessary. Not only gets the check ugly, moreover what happens if you create a sub-type with the same name as the entity type?
The more logical way would be if the system clearly states: no, this entity type does not have a sub type, instead of pretending there is one, when there is none.

@effulgentsia - why should the bundle be the same as the subtype? that's just a typical mapping.

Per #172, it's not just a typical mapping. It's the only mapping supported by Drupal currently. Do you know of any existing contrib module that has successfully enabled bundles of fields to be defined/attached to anything other than entity subtypes?

subtype = the sub-type of the entity, in other words, the actual node type, vocabulary object/name
bundle = the array of fields that are attached to a specific entity and it's subtype

This makes sense to me only if $bundle is always an array/object, but never a string. But in our current code, we never refer to the array of fields as a bundle: we always refer to it as $fields or $instances.

field_test_create_bundle() etc. are used to create or edit entity subtypes for the 'test_entity' entity during testing.

Good point. In that case, how about naming it field_test_create_entity_subtype()?

As far as field_attach_*_bundle(), I think the problem with those functions is that they're explicitly called by node_type_save(), etc. I think we should probably add functions like entity_subtype_(create|delete|rename)() to the entity system and have those functions invoke similarly named hooks, so field_attach_create_bundle() would become field_entity_subtype_create(). But I think that's out of scope for this issue.

As far as field_attach_*_bundle(), I think the problem with those functions is that they're explicitly called by node_type_save(), etc. I think we should probably add functions like entity_subtype_(create|delete|rename)() to the entity system and have those functions invoke similarly named hooks, so field_attach_create_bundle() would become field_entity_subtype_create(). But I think that's out of scope for this issue.

Totally. Those field_attach_CRUD_bundle() functions are in Field API only because back then in early/mid D7, Field API was the only thing that needed to care about entity bundles appearing and disappearing, and there was no such thing as an entity API.

Their place is totally within the Entity API, with Field API only reacting to it - but noone found the bandwidth to do the refactor so far. I think #1187784: Standardize adding a new bundle to an entity type is the closest we have to an existing issue for this.

Other than that, yeah, my comment in #160 about "collection of fields determined by something else than the entity subtype" was total sci-fi. Like I said in there, I don't really have a strong opinion on this. If everyone finds it's confusing to have Field API name $something_else a value that will de-facto and in the foreseeable future be the name of an entity subtype and is named $entity_subtype in the rest of core, then we should go subtype all the way.

We have a nice example of FieldAPI usage in brand new contact module for fields on none-storable none-fieldable entity
In this case subtype and set of fields makes much more sense

@yched - even if bundle being distinct from entity subtype is ficiton for now, I think it's important to kepe the distinction. Why not have a bundle per individual entity if you needs very specific fields for each one?

Why not have a bundle per individual entity if you needs very specific fields for each one?

Why not consider that a new entity subtype then? So, in core, for nodes, $entity_subtype = $node->type, but if someone wants to figure out how to allow specific fields for individual nodes, then what they need to figure out is how to make it so that $entity_subtype = $node->nid. Or, more likely, $entity_subtype = SOME_LOGIC($node).

The point is, in ERM, the data structure of an entity is determined by its type, where generically, type can follow an inheritance hierarchy. If you have a new data structure, then you have a new type. The word "bundle" is not used in any other ERM system that I'm aware of. Perhaps in the future, Drupal will also allow for arbitrarily deep type inheritance, but for now, we just have 2 levels, so why not call those levels type and subtype?

So right now, and contrary to what I wrote in #160, I can definitely relate to the "let's not keep a confusing double terminology to account for science-fiction" argument. We currently have no plan to make Field API support "bundle by entity", and I have no idea how it would even play with EntityNG's "properties".

So I am fine with renaming to $subtype all the way.

I'm just worried that if committed now, it will make #1735118: Convert Field API to CMI a hell to reroll. So *if* the patch here is not too hard to generate (like, mostly grep-based ?), I'd strongly suggest we wait for that other, much more critical patch to land.

I'm also fine with renaming to $subtype all the way. However (and maybe I'm just being pedantic or obtuse), I still don't think it is correct to say that "'entity subtype' and 'collection of configured field instances' are semantically the same thing." This isn't just a sci-fi distinction based on some hypothetical future evolution of Drupal.

For example, just look at node types, which are the most common entity subtype in Drupal. You can configure each content type with different settings for whether that node subtype is promoted to the front page by default, whether it displays the author's name, whether it tracks revision history, etc. None of those settings is stored in a "field." This therefore means that "entity subtype" is a container for that subtype's "collection of configured field instances" plus "some other configuration stuff."

Just my 2 cents, but the way I think about #181 is that $entity_subtype and $node->type can both be 'article', but that they are not semantically identical. The concept of a "node type" can indeed include various configuration and meaning unrelated to fields. However, the semantic concept of an "entity subtype" can only encompass concepts that apply to entities generically, not concepts that are unique to node.module. And I think "collection of configured field instances" is currently the only such concept.

Looks like #1735118: Convert Field API to CMI has been committed for the most part, so I'll look at this again.

Personally I don't like 'subtype', because it doesn't put clear what is it for. Could we create a subsubtype? And if we want to absolutely avoid any subtypes - could we? We couldn't, so imho it is not appropriate to call it so.
What about introducing 'Entity Model'? We do have 'Entity Controller' already - why don't use models?
I propose such configuration:

Entity type -> Entity model
Bundle      -> Entity type
Entity      -> Entity

It makes clear what is it for and why we can't create entity type without it - because it is a container for meta-information about how this concrete entity type is designed.
Any suggestions or thoughts?

IMHO, it's less about avoiding "subtype" (see also #95) but I'm totally convinced a type should always be a type, so a node type should be an entity type. This avoids the confusion with "type" standing for different levels of abstraction:

However, I'm afraid it might cause a WTF in practice when applying it to actual code and db schemas within entity types implementations : the "subtype" as an entity is the "type" as a node...
- $node->subtype = $node->type; // Hum...
- when looking at your {node} table in phpMyAdmin, the 'type' column is what holds the subtypes - and that's what you expose for EFQ : "read my 'subtype' property from my 'type' column".

Therefore I absolutely bought xjm's proposal from #14/#20 and the following comments (looks there was a huge amount of agreement including catch, fago, webchick, yched, bojanz etc.):

Entity type -> Entity class
Bundle -> Entity type
Entity -> Entity

Then counterarguments were raised in #28 and #36, and we got a bit astray with 'variants', 'valences' etc. which didn't bring us forward. Then a comment by Webchick was misunderstood, who was really saying "We can't rename node types" not "Let's stay with what we have." Then we got stuck and somehow returned somewhere to get something done.

I agree with yched's main counterargument that it isn't easy to communicate that node types are now something different. However, the counterargument doesn't apply to the UI, which doesn't really have the notion of entity types. It only applies to DX, which in the long run will be improved by this renaming of concepts.
And IMHO, the DX changes in D8 are so huge that this conceptual change can be communicated as well. It will convince most developers that we're unifying what a "type" is for all entities including nodes.
So this will be doable, and finally it has always been the Drupal approach to go for conceptual improvements rather than sticking with what everybody was used to.

...keeping this assigned but not working on it risks reaching code freeze without actually getting something done.

@markpavlitski: sorry Mark, if you are working on this feel free to re-assign to yourself.

@klonos That's fine, I will hold off for now until there's more of a consensus on naming convention.

Yeah, I kinda already knew that was the reason for your "inactivity". No problem ;)

...it's just that keeping an issue assigned to somebody often makes people that filter these issues out of the ones they follow miss it.

Makes sense! I'll keep that in mind next time.

FWIW, #2030569-23: [policy] Decide how to refer to "entities" and "bundles" in D8 UI makes it even more obvious that it's more clear to refer to them as subtypes rather than bundles..

Added Entity subtype option. -- m.m

I think like #186 that if bundles aren't optional and we can't attach fields to types then bundles should become types and therefore a new name for types is what's needed.

i.e.

Entity type -> Entity class/model/family/base/group
Bundle      -> Entity type
Entity      -> Entity

Bundles are optional, because they're only for fieldable entity types.

#195 I speak of entity bundles not, field bundles, and how can they be optional if different node types are used?

i.e. A new node type does not mean a new entity type, but a new bundle.

There is only one concept of bundles. And they're only used by fieldable entities.
For example, what is the bundle of an image style? A text format? A view?
There is no concept of "subtype" or "bundle" or anything for those.

More precisely content entities actually, not fieldable entities. It's perfectly valid to have multiple bundles for a non-fieldable entity.

Downgrading to normal for now. I think I'd want to see usability testing on new Drupal users whether 'bundle' or 'subtype' has an impact on finding what they want to do in the first place. I also don't love bundles as a term, but not sure type vs. subtype would be any less confusing.

A UI rename could be done in 8.x, so moving down. If we were going to change this in the API, we'd want to do it with a bc layer in 8.x as much as possible too.

However we don't use Symfony bundles at all, so that part of the issue summary is not really relevant, downgrading to 'minor' for that reason.

Also since this issue was opened we've solidified the concept of 'bundle entity' - as in a configuration entity that represents the bundle. I'm not sure a 'subtype' bundle entity that's actually a completely different entity type is a good idea.

Back to #72 let's get rid of typing in code & decide about ui labels & thier translation

In UI we have page variants (same underhood) & commerce product variations,
and it never was a question about what it means!

In entity api we use getVocabulary() & getType() - makes sense to grep d8 contrib for usage bundle() - means working at abstract model of bundles (variations of entity definition)

We have view & form "modes" - variations of cache contexts

Imo beter to set the issue as d9 target, feel free to change back

So if this is scoped to "Do UX testing to see if these renames would actually be worthwhile," according to the continuous upgrade path, it should be done in a minor release. Let's start with that scope before we do any actual UI changes or codebase renames.

I'm late to this issue, but I'd like to note that the User Guide standardized on the terms "Entity type", "Entity sub-type", and "Entity item".
https://www.drupal.org/docs/user_guide/en/planning-data-types.html

The Help Topics have also adopted "entity sub-type", but we still need to do this usability testing, decide on a standard, and then change:
- Core UI text
- Help topics
- User Guide
to all be consistent.

Updating issue summary with tasks. We still need to do this.

Also I read through all/most of the comments and added some new variation ideas to the summary.

We talked about this in today's usability meeting:
#3164615: Drupal Usability Meeting 2020-08-18

We decided that option (C) was the best idea:

Entity type -> Entity type
Bundle      -> Entity subtype
Entity      -> Entity

So, updating the issue summary. The next thing will be to patch Core and the User Guide.

Generally fine with that, what I'm concerned about is the mismatch of UI and code. It looks like this issue shifted from the original goal of renaming bundle everywhere to just doing it in the UI?

Bundle isn't used often in the UI, most places already attempt to use a more specific label when ever possible, we have concepts like \Drupal\Core\Entity\EntityType::getBundleLabel(), which shows e.g. "Vocabulary" and "Content type" instead of Bundle/Subtype. Only the fallback there is "foo bundle". It's going to be pretty hard to find those places in fact, I'm not sure what exactly to search for to find Bundle in UI texts. Maybe look for translatable strings on localize.drupal.org?

However, in code/API documentation, it's another thing entirely. There are 1700 $bundle, 1700 'bundle' and that is by far not everything. Changing that would be a _massive_ undertaking and we'd need to rename/deprecate things like entity keys, API methods and so on.

If we only change the UI and documentation then I fear we fix a UX problem but might make the DX problem even worse. It's a bit like the node/content thing, I get that using node in the UI was weird and confusing but try to explain to a developers that content in the UI is nodes entities in code and content entities is something else ;)

IMHO, we should focus on avoiding using bundle or subtype as much as possible in the UI and and use specific terms like node type, vocabulary and so on. And IMHO, we're already doing that quite well.

Based on my idea above, I searched for "bundle" in the german translation of core on localize.drupal.org and learned a few interesting things, https://localize.drupal.org/translate/languages/de/translate?project=dru...
* The german translation already uses Subtyp, you don't need to speak german to get that this means subtype ;)
* There are only 43 translatable strings using "bundle"
* Based on a quick look, most of these actually use bundle only as a placeholder name, so we only expose it to translators and not users.
* Many others are very rare, e.g. Base field bundle override is the config entity type label of a config entity type that has no UI, the only place you see it is config translation UI. And bundle might just be the least confusing part of that thing ;)
* I'd like to know what we were smoking when we created "Node Bundle", which is actually the node type (visibility) condition (\Drupal\node\Plugin\Condition\NodeType). The reason you don't see that in the UI is that BlockForm is cheating and has a hardcoded replacement to Content types in \Drupal\block\BlockForm::buildVisibilityInterface. That would be one example for a simple standalone cleanup issue. Change that label to Content type, remove the hardcoded override. Less code and everyone wins.

The reasons I would say not to change it in the code are:
a) As you noted, at least 3500 code lines to change.
b) Possible backwards compatibility issues for method/class/property names.

I agree having a mismatch between the UI (which as you noted is not full of the word "bundle" anyway) and the code is generally undesirable. But this is mitigated by, as you noted, the fact that we don't even use the word "bundle" in the UI hardly ever. And I think we can also mitigate it by adding a note in a few places to
https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Entity%21...
that what is called a "bundle" in code should be referred to as an "entity subtype" in any UI that needs to refer to bundles. And maybe adding that note to the ContentEntity base class doc blocks as well, and the Field UI module doc blocks, in a few places?

And also updating the UI text standards page to note that we should not use the word "bundle" in the UI.
https://www.drupal.org/docs/develop/user-interface-standards/interface-text

Adding a few notes to the issue summary about this...

Updating summary to link to User Guide issue and another related issue that was in the summary rather than a Related field item. Also I updated the UI text standards page.

Here is a patch. Wow, someone made a patch for this 8 years ago. I started from scratch here, since that patch was too old to be useful.

I looked through localize.drupal.org for strings containing "bundle" and "sub-type", which are the main things to get rid of for this issue. I fixed those up, plus a few other places I noticed that were not conforming to the terminology here of "entity type", "entity subtype", and "entity" (not "entity item").

I think this gets most of them.

I also made a follow-up issue to get rid of "node" in the UI, which was a goal in Drupal 7 but there are still 5 pages of strings if you search on drupal.org: #3193696: Don't use "node" in the UI

1. +++ b/core/lib/Drupal/Core/Entity/Controller/EntityController.php
   @@ -224,7 +224,7 @@ public function addBundleTitle(RouteMatchInterface $route_match, $entity_type_id
        // so fetch the raw parameter.
        $bundle = $route_match->getRawParameter($bundle_parameter);
        if ((count($bundles) > 1) && isset($bundles[$bundle])) {
   -      return $this->t('Add @bundle', ['@bundle' => $bundles[$bundle]['label']]);
   +      return $this->t('Add @subtype', ['@subtype' => $bundles[$bundle]['label']]);
        }
        // If the entity supports bundles generally, but only has a single bundle,
        // the bundle is probably something like 'Default' so that it preferable to
   diff --git a/core/lib/Drupal/Core/Entity/EntityBundleAccessCheck.php b/core/lib/Drupal/Core/Entity/EntityBundleAccessCheck.php
   

   is this worth breaking translatable strings over? @bundle is only a "translator-facing" string, not an end-user facing string :)

2. +++ b/core/lib/Drupal/Core/Entity/EntityBundleAccessCheck.php
   @@ -52,7 +52,7 @@ public function access(Route $route, RouteMatchInterface $route_match, AccountIn
        }
   -    return AccessResult::neutral('The entity bundle does not match the route _entity_bundles requirement.');
   +    return AccessResult::neutral('The entity subtype does not match the route _entity_bundles requirement.');
      }
    
    }
   diff --git a/core/lib/Drupal/Core/Entity/EntityType.php b/core/lib/Drupal/Core/Entity/EntityType.php
   

   I think we keep exception messages technical (and untranslatable) and we then have a confusing mix here.

didn't check the whole patch

I wondered about (1) too... But translators have UI issues too. They need to understand what they are translating, and they have to reorganize sentences and placeholders for their language in many cases. If "bundle" doesn't make sense as a word to people using the Drupal UI, then @bundle as a string placeholder also doesn't make sense to a translator. I think we should take the one-time hit to make the strings more understandable for translators. But we should probably get another opinion.

For (2) you are right, that particular string is not on localize.drupal.org and is not translated. Log messages are translated, but not exception messages or AccessResult messages. So we should probably take that out of the patch.

I checked and that is the only place in the entire patch that something that isn't translated is changed by the patch. So we just need to revert that one line.

And fix the test fails, which most likely are due to strings being tested for that changed.

Here's a new patch:
- Removed that one AccessResult non-translated string from the patch.
- Fixed (hopefully) the test fails.
- Removed changes of "node" from the patch. They should be addressed in #3193696: Don't use "node" in the UI to keep this in scope.

Back to the question of whether we should update strings like "Add @bundle" to "Add @subtype". A few points:

1. There are only 18 strings that have either @bundle or %bundle in them, that don't also have the word "bundle" that would appear in the UI that would need to be updated anyway (based on searching on localize.drupal.org). So, it's not a huge translation burden.
2. It seems to me that going forward, anything that confuses users in the UI would also potentially confuse translators in a placeholder name. We don't name the placeholders "foo" "bar" and "baz" -- we name them something supposedly understandable.
3. Not all translators are programmers. So, we should strive to not confuse them with things that don't appear in the UI.

Adding notes about this to the issue summary.

Yeah, I get the point, but FWIW, for all the changes, I'm less concerned about the translation effort, as you say, it's not *that* much but all the sites out there which will lose their (possibly customized) translations of these strings with a core update. That's why we used to have a string freeze in core, but I'm not exactly sure about the rules now.. I guess allowed in minor versions, which can be an annoyance.

Not saying we shouldn't do it, just that there is a cost/downside.

Agreed, there is definitely a cost/downside. Strings are allowed to change in minor versions, but we definitely should not change them for no reason. I am not sure what the right answer is here. I could definitely take those 18 strings out of the patch and kick them down the road...

Another consideration: There are things like this in the patch:

-  public $message = 'The entity must be of bundle %bundle.';
+  public $message = 'The entity must be of subtype %subtype.';

Two questions:
a) Does it make sense to change bundle to subtype, but not %bundle to %subtype?
b) If we change %bundle here to %subtype, does it make sense to leave it as %bundle/@bundle elsewhere in the translatable strings (consistency?)?

Again, I do not know what the right answer is here... ???

I think if we are changing the terminology, changing the replacement placeholders is a good idea even in the strings where the user facing word does not appear, just the placeholder. That should help with consistency and translator understanding. Otherwise its two terminologies about the same thing.