[RFC][DX] Set of commands & changes to add transparency to Flex

[weaverryan]

Hi friends!

I ❤️the recipe system. The idea of having packages auto-configure and scaffold themselves is the best. However, after a few recent conversations, I think Flex & the recipe system is a bit "murky" to people:

• they're not sure where the recipes are coming from or how to find them
• they don't know if/when they should update recipes or even how they would find which file came from which recipe to know how to find that file
• related to above, they don't know about the symfony:sync-recipes command. Rather, the installation of recipes feels like a "magic" thing that happens once, and can never be repeated afterwards.

This is a big RFC to make numerous, minor changes to help make this experience more transparent and user-friendly:

1) symfony:recipes DONE! ✅

This command would simply list all of the installed recipes, probably only listing those that actually had a recipe (not a full list of what's in symfony.lock). Ideally, it would also show you if updates are available:

Installed recipes:

 * symfony/framework-bundle 4.2
 * symfony/console 3.4 (update available)
 * ...

Run:
 * composer symfony:recipe:show vendor/package to see details about a recipe.
 * composer symfony:recipe:update vendor/package to update that recipe.
 * composer symfony:recipe:blame to see a tree of all of the installed/updated files

2) symfony:recipes:install DONE! ✅

This would simply be a rename of symfony:sync-recipes. It's "installing" recipes, so i think it makes more sense.

3) symfony:recipe:update

This would effectively be an alias for the current symfony:sync-recipes --force. The name "update" is more revealing to what it does. However, because it's not a real "merge/update", we'll of course still have output that describes what happened and how to proceed, etc.

Additionally, it will now accept the package name(s) that should be updated:

composer symfony:recipe:update symfony/framework-bundle

When using this option, I think we should also print a list of the PR's that updated the recipes, for each updated library:

Recipe updates for symfony/framework-bundle:
* ensure $_ENV is contains real env vars from $_SERVER , or defaults from .env.local.php
    https://github.com/symfony/recipes/pull/611
* Don't use putenv by default
    https://github.com/symfony/recipes/pull/572

4) symfony:recipes <package/name> DONE! ✅
Usage: composer symfony:recipes symfony/framework-bundle

This would simply tell you what version you have installed, where to view that recipe (URL on GitHub), and any updates available. It's a nice way to see what might be updated before actually running symfony:recipe:update.

This might also print a "tree" of what files this recipe added/updated, with a message to run symfony:recipe:blame to see this for all recipes:

## symfony/framework-bundle recipe
version: 4.3
sha: cb4152ebcadbe620ea2261da1a1c5a9b8cea7672
View recipe: https://github.com/symfony/recipes/tree/4a4625ad7cc41a25e5dcc4ac3c91f6ea847f815f/symfony/framework-bundle/4.2
Status: Out of date

Files:

- .env
- .gitignore
- config/
  - bundles.php
  - services.yaml
  ...
- public/index.php symfony/framework-bundle

Update this recipe by running composer symfony:recipe:update symfony/framework-bundle

5) Commit the recipes to the skeletons

This is an idea by Nicolas. The problem is that it's very difficult to see the files of a recipe - you need to know which directory/version to navigate into, and they're not versioned in a traditional way. One way to solve this for the most important recipes is to commit them to symfony/skeleton & symfony/website-skeleton. This is mostly easy, though there is one technical "thing" to fix, which would be to make sure the symfony/framework-bundle post-install message still shows up (even though the recipe was previously installed).

6) Mention symfony:recipes:install while installing recipes

When a recipe is being installed (e.g. after composer require), the messaging currently looks like this:

Symfony operations: 4 recipes (ea40ff3f6315d74e928af253b509b9d1)

Instead, let's make it more obvious that what's really happening is really
that a command is being run (well, internally, we're not calling the command,
but calling the command would have the same effect). This removes some of the
Flex mystery, and helps discover other Flex command:

Installing new recipes:
    composer symfony:recipe:install
    - Configuring doctrine/annotations (>=1.0): From github.com/symfony/recipes:master

7) symfony:recipe:blame to show source of files

To answer the question: what recipe did this file come from? We could have
a symfony:recipe:blame command, without output something like this:

- bin/console symfony/console
- config
    - bootstrap.php symfony/console
    - packages/
        - messenger.yaml symfony/messenger
        - framework.yaml symfony/framework-bundle (update available)
        - ...
- .env symfony/messenger, doctrine/doctrine-bundle, ...
- public/index.php symfony/framework-bundle (update available)

8) Discovering outdated recipes/other commands

This is all meaningless unless the user is able to easily discover these commands. To help with that, I propose 2 things:

A) During a composer update/composer require, check for any outdated recipes and
print a message if there are any.

3 Symfony recipes have updates available. Run composer symfony:recipe:list
for details.

B) During a composer install, always show a little message:

Run composer symfony:recipe:list at any time to see a status of your
Symfony recipes.

[nicolas-grekas]

I like it :)

• I would suggest adding an "s" to "recipes" commands.
• I would add one more command, to display the post-install messages on-demand.
  eg symfony:recipes:show-post-install-notes $optionalRecipeName (or shorter :) )
• symfony:recipes should probably be an alias for (or the name of) symfony:recipes:list
• but we don't need that "list" command: symfony:recipes:show without arguments does it.
• recipes:update shouldn't be destructive on first call: --force would be required to do the changes and it should be a dry-run by default
• I think we don't need recipes:install at all (we would rename "update" to "install" then). One less command is a win.
• for recipes:show, we don't have the info right now to know which files have been updated. I would make it list the files that are listed in symfony.lock for now, and improve if needed. Improving would mean fetching the manifest.json from the tree, and code rules based on which configurators are found there. Doable (but fetching the tree would need a new endpoint from the flex-server, unless we want to bind the plugin to github - which we don't :) )
• displaying the log of updates + linking to related PRs looks nice but challenging - would benefit the "show" command too btw.

With this in mind, I think there are some low hanging fruits already, PRs welcome :)

[Pierstoval]

Excellent idea! 👍

[DylanDelobel]

What about adding an optional path arg to install command?

To store a local copy of the recipe in our bundles directly

In that way, we are not tied to the official/recipes-contrib repo and the internet

[linaori]

Commit the recipes to the skeletons

Does this mean we will have inline recipe support? Would solve #206

[nicolas-grekas]

@linaori nope, here it's about playing the recipes on a dummy repo where they are all applied, and version the result of this e.g. once a day. This would provide a convenient way to browser recipe effects and their history all in one place.

Inline recipes is unrelated to this issue /cc @DylanDelobel too

[noniagriconomie]

Very interesting indeed :)

can i suggest as well to mark as deprecated packages listed on https://flex.symfony.com ?
so that no need to go on the package website to see it is deprecated, and not install it also

thank you

[teohhanhui]

symfony:recipe:update should take a page out of system package managers, e.g.:

apt: .dpkg-old / .dpkg-new
pacman: .pacnew

[yvoyer]

great idea, but could I suggest using another term for the blame command. blame seems hard, what about debug, or dump?

[atompulse]

Another aspect that would make the process more transparent is to know upfront which folders/files will be created when installing.
Also it would be nice to have an option to be able to stop flex from DELETING those files with an option or something when uninstalling.

[maxhelias]

Great idea, I would also add a command to display the list of command added by Flex like symfony:recipe:help

WDYT ?

[xabbuh]

What about a command like pack:show that gives you a list of packages that a pack depends on? So basically what dependencies would be added to your composer.json file when the pack is unpacked (see also symfony/symfony-docs#12354 (comment)).