Generated with the help of my own dear MeatBrain.
Problem/Motivation
There are some situations where a module should ship recipes, or a set of recipes, that set that module up in various ways. An example is https://git.drupalcode.org/project/canvas/-/merge_requests/2070, where Canvas wants to ship a recipe that sets up OAuth for Canvas CLI (which would otherwise be an arduous, persnickety process).
In these kinds of situations, the recipe is pretty tightly coupled to the module in question, and stays within the boundaries of that module. But a bigger recipe, like a site template, might want to invoke that recipe. In other words: "in this site template, I would like to set up Canvas OAuth in a specific way that Canvas OAuth defines/maintains".
Recipes have no syntax for this. There's no way to include "a specific recipe that is embedded in a module". The only way to make that work is for the recipe in question to be split out into its own project, which is both complicated and adds substantial maintenance burden.
Proposed resolution
Support this syntax in recipe.yml:
recipes:
- @canvas:a_recipe
This means "include path/to/canvas/recipes/a_recipe/recipe.yml".
Intentional limitations:
- The
canvasmodule must exist, although it need not be installed. This is just a normal dependency: if this recipe wants to apply another recipe from Canvas, it behooves the recipe to depend on Canvas. - This only works with modules, not themes. I can't think of any real reason why a theme would need to ship various "set me up in different ways" recipes, but if the need arises, we can always add that in a follow-up. For now, we'll limit it to modules to keep things simple.
Remaining tasks
Create follow up for:
The . character cannot appear anywhere in the include string, to prevent path traversal (and in fact, this should have already been the case for every other kind of recipe include, so let's fix it here as a deliberate hardening).
User interface changes
None.
Introduced terminology
None.
API changes
Yes, recipes will support a bit of new syntax.
Data model changes
None.
Release notes snippet
TBD but I bet we'll want one.
Issue fork drupal-3639289
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #2
phenaproximaComment #4
phenaproximaOne bit of future scope here, which I don't think we need to handle in this issue, is how to handle inputs to recipes that are referenced this way. It's probably going to take the form of
--input="@canvas_oauth:my/recipe.SOME_INPUT_NAME=value", and that's awkward as all hell, but that's why I think it's something to punt rather than handle here. Tagging for a follow-up though.Comment #5
phenaproximaComment #6
nicxvan commentedAdding a note from slack, I am in favor of this.
I think we should keep some of the current restrictions, they have to be in the recipes subdirectory, and we should reference them like SDCs.
Comment #7
phenaproximaAgreed, @nicxvan, and implemented in https://git.drupalcode.org/project/drupal/-/merge_requests/17854/diffs?c....
Comment #8
nicxvan commentedThis is very clean.
I'm surprised it's so little code.
I think the symmetry with sdcs and the root recipe is nice.
The earlier iteration would not have worked with recipes in subdirectories anyway.
CR looks good!
I moved the . in the issue summary to remaining tasks, we should create a follow up for that.
Comment #9
alexpottIt looks like we should improve the validation in
This could stop recipes from doing path traversal. +1 for this being in a follow-up and also prevent this on an API level.
Putting back to needs work for the follow-ups to be created. The code looks good to me... can be set back to rtbc once they both exist.
Comment #10
phenaproximaOpened both, and linked here. Back to RTBC.
Comment #11
benjifisherI am also in favor of this issue.
The use case I have in mind is letting a module provide an "example" or "quick start" recipe. Until now, the only way to implement this is with a
mymodule_examplesubmodule.Should we add a follow-up issue for the
project_browsermodule to support recipes included in modules? That makes sense for my use case, but not the one described in the issue summary.Comment #12
phenaproximaYeah, I think a follow-up in Project Browser makes sense.