Decide on naming convention on recipes

Proposal to update the naming conventions to bundle_id/descriptor.

As discussed in https://www.drupal.org/project/distributions_recipes/issues/3417835#comm... → , this will make it much easier to to deduce what a recipe does.

You can see the changes here:
https://git.drupalcode.org/project/distributions_recipes/-/merge_request...

If this is accepted, the Standard recipe will need to be updated in a follow-up ticket.

Why not update Standard in this issue? We could open a separate MR against 11.x, in the same issue, which would update it.

I assumed the changes to the docs would need a Mr on this ticket to the 1.x branch and we would need another for 11/10.3.

We'll need another MR, but there can be more than one MR per issue. :)

I do feel as of that Recipes has Config Actions, Entity Actions, Method Actions as verbs
I suggest that they start with a verb, or keep the subject targeted first.

The setup/install type
setup-my-ai-recipe
setup-webreleases
init-drupal-demo1
init-drupal-demo2

Adding features type
add-my-ai-recipe-option1
add-my-ai-recipe-option2
add-products
add-projects

Updates - update/change/switch
drupal_update_1003
users_update_10012
fix-mismatched-config-for
reset-default-config-for
remove-non-existent-permissions

Env
change-on-dev
change-on-test
change-on-prod

.. somthing as the folloiwng could be easer to understand from the first time

recipes:
  - add-article-content-type
  - add-taxonomy-tags

or

recipes:
  - init-article-content-type
  - init-taxonomy-tags

Having the following as -- the module/entity name first then the bundle

recipes:
  - content_type_article
  - taxonomy_tags

Do we need to think more high level about this? The "Types" are very Drupalistic being a Content type or a User Profile, but for findability, Project Browser's "Use Cases" are more appropriate.

And to be able to limit and sort recipes in Project browser, I am thinking we need a third sort, something along the lines that @chrisfromredfin is using "ingredients, dishes, and meals" to sort the impact/size of the recipes. See: https://drupal.tv/external-video/2023-11-19/drupal-recipes-what-are-they...

If "ingredients, dishes, and meals" are to squishy, we could consider using Atomic Design's nomenclature of Atoms, Molecules, Organisms, Templates, Pages.

In the issue description, it says that "site feature" is commonly used, but the wordpress.com example is using "your site's features." These are just English words used together in a sentence, not a unit that is commonly used. I'm not sure what the benefit of prepending "site" to "feature" is, unless this issue is a proposal for core or Drupal CMS recipes only, which is not clear from the description. Feature seems a better alternative than site feature.

I'm likely missing some context that isn't in the description, but it seems to me, that just like modules and themes, recipes will need short descriptions for both their page on drupal.org, and eventually for project browser. I'm not sure that mandating a name is all that useful or enforceable.

I think it is hard for the name to provide enough information about the type of things done in the recipe, the intention of the recipe, and the scope of the recipe. I feel like it would be better to focus on better descriptions, and consider some type of mechanism for automating a summary of the actions a recipe will take in a way that it can be more easily absorbed than by reading the yml file, etc.

Something along the lines of headings like:

Modules Installed

Config Modified

Actions Invoked

Content Added

with summaries in them. We wouldn't want to dig into deep detail, but could give a summary that should along with a short description, give a good idea that the recipe does what you think it does.

Although I think option 2 of adding a second classification is elegant, I worry that it will be difficult to execute correctly. Atomic design is generally contained within one project or design system, with one set of people making the designations. Since recipes will be shared widely, this classification system only works well if everyone is using it in the same way, right? In that case I don't think it's feasible?

Unfortunately I don't think that even prior knowledge of atomic design is that helpful, I am sure we have all seen a site that used the concepts in a way that is totally incomprehensible!

I also agree with @ultrabob, here are some draft mockups we did for the recipe detail in Starshot. In mapping this out, I realised it is difficult to show everything you might need to know here, because 1) recipes could do a LOT of things at once, making a wall of text and 2) recipes can apply other recipes, so do we try to surface ALL of that?

The issue summary seems to assume that a recipe will only provide a single entity configuration, such as a content type. I would argue that this is too narrow a way of thing about the potential of recipes, and will lead to very limited usefulness for the site builders meant to use them.

I have been working for a while on a set of modules with a similar concept to recipes, that I called Configuration Kits. Typically each one would include a content type (or other bundle) but also one or more views to display the content that would be created, and often some thought as to the administrative experience of adding and managing content. For example, some include a view that incorporates DraggableViews to ensure there's an easy and intuitive way to set the order in which data will be displayed.

Would argue that we should try and thinks of recipes as systems: an event calendar, a staff directory, a locations map, and so on. When creating a site, the site builder can add recipes for the systems they need, and then tune the fields and other details to better match the specifics their site needs. Or, they can add systems over time after the site has been created.

I would think a "site" recipe should be mostly just a meta recipe that pulls in a number of these solution-based recipes. These site recipes could be meant to address a common use case: publishing site, educational institution, etc.

The versatility of recipes makes it difficult to even describe them, let alone come up with a naming convention.

I think it's fine that some recipes simply provide a content type but some provide comprehensive systems. It seems also that Option 1 aligns with this and what you are saying where site feature = system? But then that isn't covered in the proposed naming convention specifically (yet).

Maybe this should be two separate issues, the naming convention and a new one for the sub-type classification. Or maybe the first part just needs an example of a system name?

@mandclu directed me here. I did not even know "Site" type recipes exist, but they appear like only a docs concept. I think eventually Project Browser needs to differentiate between the "Site starter" and "Site feature" level recipes and not necessarily offer the basic component recipes that are there for reuse, so these classifications would need to show up somewhere on the recipe structure level. This is not necessarily a requirement I think for Starshot, since Starshot's early versions can hardcode lists of recipes in these categories in their project browser source plugins I think, but ultimately this will be needed.

Just putting this out there... Could the release version of Starshot be a site recipe?

BTW I added this as a post-MVP to #3449347: [META] Recipes, Package Manager and Project Browser improvements needed for Drupal Starshot → . It would be nice to have it earlier but not a must IMHO.

In the issue description, it says that "site feature" is commonly used, but the wordpress.com example is using "your site's features." These are just English words used together in a sentence, not a unit that is commonly used. I'm not sure what the benefit of prepending "site" to "feature" is, unless this issue is a proposal for core or Drupal CMS recipes only, which is not clear from the description. Feature seems a better alternative than site feature.

The term "Feature" is already in use in the Drupal space with the Features module. I added Site to differentiate.

I did not even know "Site" type recipes exist, but they appear like only a docs concept.

The Standard recipe is a "Site" recipe.

https://git.drupalcode.org/project/drupal/-/blob/11.x/core/recipes/stand...

Which, thanks for bringing that up. It appears like we added a few more Recipe types in the Standard Recipe. Added an issue to update them in #3449438: Document new Recipe types that were added in core's Standard recipe →

I did not even know "Site" type recipes exist

"Additionally, the type 'Site' means that the Drupal recipe will be listed in the installer. " - this information is in example Drupal recipe file https://git.drupalcode.org/project/distributions_recipes/-/blob/1.0.x/do...

Yes, but that hasn’t come to fruition yet.

We had a conversation around this a couple weeks ago in slack at the Distribution Modernization Initiative meeting. Posting here for posterity.

As a TL;DR for the naming convention for recipe names some of us liked the idea of [drupal_entity_type]_[unique_name], i.e content_type_blog, content_type_event, etc. We also had the thought of trying to stick close to what core provides for it's config naming scheme as that will help us as developers mentally keep track of things. One thought was to even include periods in the name like core does, for example node_type.event as a recipe. We hadn't tried it out, but maybe recipes will allow folder names to include periods in their names? TBD.

Also, from a developer perspective imagining them in a list in a yaml file where you have to maintain that is something I think we want to keep in mind as well. It will get hard to tell what recipes are doing if we don't have a standard.

I personally like the idea of where [#10] is going, but we would really need to align on the verbiage used. Allowing for folks to mix-and-match will make it very difficult to quickly determine what a recipe is doing.

Regarding the Recipe types and classification portion of this IS I think needs to be broken off into a separate issue from the naming convention discussion of this issue.

To add my thoughts though, I'm personally a fan of [#18] with the concept of providing "kits" to get folks off the ground quickly. A great example is the module Smart Date Calendar Kit → that @mandclu maintains. This to me is what an ambitious site builder is going to look for and gravitate to more. They don't want to think about node types or setting up views. What they want is functionality that will provide them value out of the box with little to no additional configuration needed.

Recipes can be any shape and size and that is part of the problem we're running into when we talk about how we classify them. As developers we should want to and probably start looking at having small recipes to establish generic content / paragraph types quickly and then look to extend those in more functional kit-like recipes.

At a high level I see we have 3 basic categories:

1. Scaffold / Skeleton / Foundational Recipes - These are the low level "provides XYZ content/paragraph type" recipes
2. Functional (Kit) Recipes - These build on top of the lower level recipes and provide additional functionality (event calendars, workflows, etc.)
3. Site Recipes - These include everything above, like what Standard recipe provides

There's lots of room for additional sub-types within these 3 basic categories, but in my head that's where I see big distinctions between the size and scope of recipes.

@carsoncho: I like those three levels, we should codify the type naming for them, so that tools like drupal.org's API endpoint can properly expose them and Project Browser can offer a UI to find them (or hardcode filters for them). What's in the way to codify this?

So we change type to have 3 different options.

Foundational - Simple recipes that provide reusable configuration primarily for other recipes to reuse.
Kit - Recipes that provide a complete functional solution for a site feature (SEO tools, event calendars, workflows, etc.).
Site - Recipes that provide complete website starter solutions like what Drupal core's Standard recipe provides.

1. Do we need a second classification type to cover the Foundational descriptive types that we currently have defined? (Text format editor, Content type, Taxonomy, etc)

- or -

2. Do we assume that if it is one of the existing type (Text format editor, Content type, Taxonomy, etc) that it is Foundational?

Big +1 to the the 3 type options proposed (Foundational, Kit, and Site).

When I look at the project root for Drupal CMS, or within any module that contains multiple recipes, I think it would be helpful if there was a directory structure that mirrors these types. Off the top of my head:

/recipes/foundational/...
/recipes/kit/...
/recipes/site/..

This way, a developer would be able to quickly identify which was which without inspecting their recipe.yml file.

As for a second classification type, I don't have a strong opinion other than a standard naming convention could go a long way in providing this type of classification for foundational recipes.

-mike

Subfolders are not currently allowed. The recipe runner only looks for recipes in a sibling folder. Allowing subfolders could lead to naming collisions as you could have a content_type_page in multiple sub-folders and which one would a recipe that depends on it apply?

Allowing subfolders could lead to naming collisions as you could have a content_type_page in multiple sub-folders and which one would a recipe that depends on it apply?

@thejimbirch - ah, makes sense. Thanks for the explanation.

-mike

I think text format editor, content type, taxonomy, etc. type of a recipe would not appear as a site or a kit, so at best it would be a subtype of a foundational recipe (if recipes want to do subtyping that is). Would be great to run the three types through the initiative meeting and get feedback there. Then move forward to codify this as it would help move with project browser's listing.

Chiming in with just some real-world experience that three levels feels intuitively correct, as it's what we ultimately settled on (with meals, dishes, ingredients). In parallel, our "meals" are recipes that get very opinionated about the whole "Site" - like how we will configure and use Layout Builder as a content paradigm overall, ex.g.

These meals depends on "dishes," which provide a smaller piece of the meal. We might add 2 dishes (an event content type and a blog content type), but we could also add 4 (maybe, a contact form and a site search). By necessity, our blog post and event content types ("Kits") use the Layout Builder paradigm specified by the meal/"Site".

Ingredients are smaller components that are needed to assemble a dish. In this realm, we have a "caption" field, that may be used/re-used by any number of dishes. These would be the "foundational" ones.

Though partial to the recipes terminology because it's cute, I get that that may not be the best user experience. That said, my initial thought was that "foundational" was "paradigmatic" - that is, I thought "foundational" was what "site" actually is, until I re-read it. I might consider something like "basic" or "fundamental" - at the risk of causing a bikeshed about it.

Re #28:

1. Do we need a second classification type to cover the Foundational descriptive types that we currently have defined? (Text format editor, Content type, Taxonomy, etc)

- or -

2. Do we assume that if it is one of the existing type (Text format editor, Content type, Taxonomy, etc) that it is Foundational?

If we think about how a user will search for Recipes within the context of Project Browser and/or eventually on D.O we'd want to think about these through the lens of the Ambitious Site Builder and what makes the most sense to them. I know I have a jaded/biased lens as a developer, but to me it seems the persona we're targeting for wouldn't find much value in searching for a single "foundational" recipe by itself, but I'm happy to be wrong on that if folks think otherwise.

I'm with Gábor on #32 -- these sub-types don't make sense being tagged as part of a "kit" or "site". To me it seems like these sub-types "Text format editor", "Content type", "Taxonomy", etc. are all sub-types or 'tags' of "foundational" recipes. Kind of analogous to the "Module Categories" on the module search page.

These foundational recipes seem more useful to a developer who doesn't want to potentially reinvent the wheel if a recipe already exists to serve their needs vs. the ambitious site builder.

Have we brought this proposal of the three types to the initiative meeting to discuss? If so, was there any consensus or changes we should make based on that discussion?

I did not feel like we got consensus in the initiative meetings where it was discussed.

Nov 5th
https://drupal.slack.com/archives/C2THUBAVA/p1730828173029409

Nov 19th
https://drupal.slack.com/archives/C2THUBAVA/p1732037050881159

We're starting to get there. A bit more discussion happened on the the Nov 5th thread and I'm in agreement with a lot of what was being talked about there.

Based on what I'm reading I believe we're all in agreement that we need some amount of sub-typing for further categorization to be used in Project Browser or on D.O. The sub-typing can be a bit more freeform then what I think we're wanting with a more concrete "type".

I like "approach B" from this last comment in the Nov 5th thread

... B)
What do you think of this approach:
- In recipe.yml, we only define one level: foundational | kit | site.
- On drupal.org, we add “tags” to each recipe project page, where we can assign multiple tags.
This way, I could filter by types (e.g., foundational+kit) and tags (e.g., SEO) to narrow down the search.
I haven’t been involved in the entire analysis process, so I may be missing some assumptions, and this idea could be off, but it’s what came to mind after reading this thread.

This aligns with what I was expecting. In my mind we set a "type" at the code level in the recipe.yml, but utilize "tags" on the recipe project page for further categorization.

I have checked out the MR in 110 to make the code change to make the "type" required and be exactly one of the following: `foundational`, `site`, or `kit`, but I still need to go through and update the core recipes to adhere to these concrete types. Figured before I commit and push those changes to make sure it is what we want. I'll hold off on committing that for now.

One concern to bring up with this approach is that code is tied to a "release" not a "project" - so as a gross example, version 1.1 of a recipe can be a "kit" and then 1.2 can be a "foundational" - not that that makes sense, but it is possible.

So, if you're trying to mix and match things in code and things on d.o (as you are with the "sub-type" versus the "tags") I might encourage you to put them all in the same place (d.o)

Also, I would encourage you to look at the newly-revised categories we came up with for modules to see how close they might come to the categories you would want for your recipes.

@chrisfromredfin where would the best place to review those categories be? The module search page on D.O?

@carsoncho. The new categories for projects(modules) on D.O with their descriptions, can be found at https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or... →

After reviewing the module category list I would argue those are categories would best be suited for recipes that we're calling "kits". These "kit" recipes provide functionality that I believe would fall into one of those module categories since these recipes often require at least one module and does some initial configuration to provide a working starter-kit for some functionality like these "Functionality specific recipes" → .

"Foundational" recipes are small scoped configuration items pertaining to a particular subset of config and there's documentation in MR 107 that I believe we have a good amount of sub-types for:

• - Block type
• - Contact form
• - Content type
• - Editor
• - Field
• - Media type
• - Responsive image
• - Site
• - Taxonomy
• - Text format
• - User role
• - User type
• - Workflow

"Site" recipes in my mind would eventually replace what we have here on the distributions page https://www.drupal.org/project/project_distribution → . There's no categories to interact with there, but we should think about coming up with those as part of this. I get the sense that because "distributions" or install profiles will be easier to achieve with recipes that we'll be seeing an influx of those soon.

I do agree with #37 in that because there's nothing stopping a developer from changing types between version of recipes I do think it makes sense to manage them all in one place and I do think D.O is the better place to do that. There's really no value in a "type" being set in a recipe.yml right now as it serves no purpose.