Recipe naming best practices

A recipe's name is the folder in which the recipe.yml and it's dependencies are kept. A human readable name can be provided in the recipe.yml file along with a description. This information is used in other tools like Project Browser, and the Drupal CMS installer to present details to the end user.

Recipes are classified into types, which is also defined in the recipe.yml, but at this time, it is a documentation only specification, meaning the recipe system is not validating or parsing this data.

Core's recipe naming

As we converted Drupal core's standard install profile to recipes, we defined the list below of recipe types. They were defined in the recipe.yml files of core's recipes, and used to define the names/folder names of core's recipes.

Contrib recipe naming

Again, while there is no steadfast rule, you will find that a lot of the early adopters of recipe authoring are following the structure prefacing the type with a unique name.

Examples: fourkitchens/sous-paragraph-types kanopi/saplings-content-base-seo specbee/storm_cms_person

Purality

In many cases, a particular type can be used in either of two contexts: * Single. The recipe provides a single configuration item of the given type along with, in some cases, directly dependent configuration. * Multiple. Generally the recipe should not provide configuration directly but instead apply other recipes that do.

List of Recipe types

• 'Administration'
  • Single:
    • Naming pattern: none.
    • Usage: adds configurations/modules related to site administration.
    • Example: a basic_shortcuts recipe that provides a basic set of shortcuts for logged-in users.
• 'Block type'
  • Single:
    • Naming pattern: [type]_block where [type] is the block content type.
    • Usage: provides a block type and associated configuration such as an entity view display.
    • Example: a basic_block recipe that provides a basic block type.
• 'Comment type'
  • Single:
    • Naming pattern: comment_[type] where [type] is the comment type.
    • Usage: provides a comment type and associated configuration.
    • Example: a comment_base recipe that allows commenting on content.
• 'Contact form'
  • Single:
    • Naming pattern: [id]_contact_form where [id] is the ID of a contact form.
    • Usage: provides a contact form.
    • Example: a feedback_block recipe that provides a feedback contact form.
• 'Content field'
  • Single:
    • Naming pattern: [type]_[id] where type is a content type and [id] is the ID of a field minus any field_ prefix.
    • Usage: adds a field to a content type and adds the field to relevant entity field and form displays.
    • Example: an article_tags recipe that adds a tags field to an article content type.
• 'Content type'
  • Single:
    • Naming pattern: [type]_content_type where [type] is the content type.
    • Usage: provides a content type and associated configuration such as an entity view display.
    • Example: an article_content_type recipe that provides an article content type.
  • Multiple:
    • Naming pattern: [descriptor]_content_types where [descriptor] describes a group of content types.
    • Usage: applies other recipes that each provides a single content type.
    • Example: a standard_content_types recipe that applies the recipes that provide two commonly-used content types.
• 'Editor'
  • Single:
    • Naming pattern: [id]_editor where [id] is the ID of the editor.
    • Usage: provides an editor.
    • Example: a basic_html_editor recipe that provides a basic_html editor.
  • Multiple:
    • Naming pattern: [descriptor]_editors where [descriptor] describes a group of editors.
    • Usage: applies other recipes that each provides a single editor.
    • Example: a standard_editors recipe that applies the recipes that provide three commonly-used editors.
• 'Maintenance'
  • Single:
    • Naming pattern: [type]_maintenance.
    • Usage: sets up modules recommended for site maintenance.
    • Example: a core_recommended_maintenance recipe that adds modules like dblog.
• 'Media type'
  • Single:
    • Naming pattern: [type]_media where [type] is the media type.
    • Usage: provides a media type and associated configuration such as an entity view display.
    • Example: an audio_media recipe that provides an audio media type.
  • Multiple:
    • Naming pattern: [descriptor]_media_types where [descriptor] describes a group of media types.
    • Usage: applies other recipes that each provides a single media type.
    • Example: a standard_media_types recipe that applies the recipes that provide several commonly-used media types.
• 'Performance'
  • Single:
    • Naming pattern: [type]_performance.
    • Usage: sets up modules for improved site performance.
    • Example: a core_recommended_performance recipe that adds modules like page_cache.
• 'Responsive image'
  • Multiple:
    • Naming pattern: [descriptor]_responsive_images where [descriptor] describes a group of responsive image types.
    • Usage: provides two or more responsive image types. May also provide one or more image styles. Note: provisionally, in contrast with many other recipe types, multiple responsive image types are directly provided, rather than each being provided in its own recipe. Rationale: the responsive image styles are only usable as a set.
    • Example: a standard_responsive_images recipe that provides two responsive image types and related image styles.
• 'Search'
  • Single:
    • Naming pattern: [type]_search.
    • Usage: sets up search in the site.
    • Example: a content_search recipe that adds page that can search site content.
• 'Site'
  • Single:
    • Naming pattern: none really, just [name] where [name] is a machine name for the site recipe.
    • Usage: the type 'Site' is a special case that allows such Drupal recipes to be listed on the installer.
    • Example: an standard recipe that provides a standard site with commonly used features pre-configured.
• 'Taxonomy'
  • Single:
    • Naming pattern: [id]_taxonomy where [id] is the ID of a taxonomy vocabulary.
    • Usage: provides a taxonomy vocabulary. May also provide a field storage for an entity reference field referencing taxonomy terms for use with the vocabulary.
    • Example: a tags_taxonomy recipe that provides a tags vocabulary.
• 'Text format'
  • Single:
    • Naming pattern: [id]_format where [id] is the ID of the format.
    • Usage: provides a text format.
    • Example: a basic_html_format recipe that provides a basic_html format.
• 'Text format editor'
  • Single:
    • Naming pattern: [type]_format_editor where [type] is the text format type.
    • Usage: sets up a text format along with an editor.
    • Example: a basic_html_format_editor recipe that adds "Basic HTML" text format along with WYSIWYG editor and related configuration.
• 'Theme'
  • Single:
    • Naming pattern: [name]_[type] where [name] describes the theme and [type] indicates whether the theme is a front-end theme or an admin theme.
    • Usage: sets up an admin or front end theme on the site.
    • Example: a core_recommended_admin_theme recipe that adds "Claro" as the administrative (backend) theme.
• 'User role'
  • Single:
    • Naming pattern: [id]_role where [id] is the ID of the role.
    • Usage: provides a user role. Typically the role is provided without any permissions, as permissions will be added by other recipes via config actions.
    • Example: an administrator_role recipe that provides an administrator user role.
  • Multiple:
    • Naming pattern: [descriptor]_roles where [descriptor] describes a group of roles.
    • Usage: applies other recipes that each provides a single role.
    • Example: a standard_roles recipe that applies the recipes that provide two commonly-used roles.
• 'User type'
  • Single:
    • Naming pattern: user. Core only supports a single user type, so it's not foreseen that more than one recipe of this type is needed.
    • Usage: provides configuration for core's user user type.
    • Example: a user recipe.
• 'Users'
  • Single:
    • Naming pattern: user_[action] where [action] is the update done by the recipe on user accounts.
    • Usage: adds additional features to user accounts.
    • Example: a user_picture recipe that adds the ability for user accounts to have pictures (avatars).
• 'Workflow'
  • Single:
    • Naming pattern: [id]_workflow where [id] is the ID of the workflow.
    • Usage: provides a workflow.
    • Example: a editorial_workflow recipe that provides an editorial workflow.