Improve discoverability of recipe changes

[javiereguiluz]

Related to this -> symfony/symfony-docs#13753. A user complained that it wasn't easy to discover that there were some very important changes from Symfony 5.0 to 5.1 in some recipes (mostly about the Kernel.php file).

It's true that developers know about composer sync-recipes, etc. but maybe we should be more proactive when upgrading packages to remind devs that there might be super important changes in the recipes of their dependencies. I don't know exactly how to solve this issue ... but I think this is an issue.

Thanks!

[nicolas-grekas]

No changes in recipes are super important... It's never a must to sync recipes when upgrading to 5.1.

[javiereguiluz]

I disagree a bit:

• In 5.0, Kernel loads YAML, XML and PHP routes and config ... in 5.1, it only loads YAML.
• In 5.0, the front controller, console script and tests use a config bootstrap file. In 5.1 that file doesn't even exist.
• 5.1 changes a bit how the APP_SECRET parameter is defined.

These changes are not important in the sense that your app breaks. Your app will keep working WITHOUT making these changes. The problem is that you are "left behind" with an "outdated way of doing things". For example, you read Symfony 5.1 docs and suddenly everything is different than your 5.1 app (because you didn't apply these recipe updates).

[pbowyer]

I didn't know of composer sync-recipes until today, when @javiereguiluz talked about it. It has been weird when after upgrading through a few minor releases I find the docs no longer match my files.

Or when I start a new project, and realise they are different. My solution has been to create a new project every now and then and manually diff the files and then update my existing project.... so yeah, I'm in favour of Flex telling me when files it would set up are different to the versions I have (minus my edits).

Adding "Run composer sync-recipes" to the UPGRADING files would help (unless it's been there all along and I've missed it 15+ times)

[Amunak]

It would be nice if composer sync-recipes (or a similar command) could output the changes and do the diffing for us.

Or we could do it like package managers on Linux: create .flexnew files with the new contents so that the developer can diff it themselves. For files that are in the original state you could update them immediately (the developer still needs to commit so it's an affirmative action anyway) - maybe, when possible, do this even to additions to changed config files, but that could be hard. Trivially you could just try to apply a diff, and if it does apply, great. If not, create the .flexnew file.

Or do both - create the new files with changes, then have a command that can find them and do the diffing and asks you for action (on Fedora/RHEL the rpmconf command does this).

But yeah, I definitely agree that this process should be better. At the very least the developers should be notified to run sync-recipes and that the recipes changed (and for which package).

[ahundiak]

I rely on the "Living on the Edge" blog posts just to sort of keep up with changes. In addition to some sort of automated process I would suggest routinely adding a "New in 5.x: Recipe Changes" post which would detail any changes. I know, more work for Javier. But it might help.

[stof]

It would be nice if composer sync-recipes (or a similar command) could output the changes and do the diffing for us.

composer sync-recipes --force will apply the recipes again. For the diffing, git diff (or the equivalent if you use another VCS tool) already does the work perfectly.
The issue discussed here is the need for awareness about sync-recipes.

[liweiyi88]

What is the difference between composer recipes:install and composr sync-recipes? I watched the "upgrading symfony course" of symfonycasts and it showed examples of using composer recipes:install for upgrading symfony app, so which command is a preferred way of upgrading symfony recipes?

[maxhelias]

@liweiyi88 It's the same. composer sync-recipes it's the old name

[maxhelias]

@javiereguiluz @nicolas-grekas I think we can display an information message concerning recipes after each composer updade thanks to Flex ?

Firstly, that it's on each command and potentially secondly (if not too heavy) to check if recipes need to be updated

[wouterj]

I do believe a CHANGELOG somewhere somehow (at least for super important recipes like FrameworkBundle) would be nice too. I'm in charge of doing composer sync-recipes --force for my company and this often takes quite a bit of time:

1. In order to avoid a major git diff, this command has to be run for each package individually
2. After seeing the git diff, I need to look for the github PR/issue for each change to see why the change was done, if this applies to our application and if something else needs a tweak
3. Then I commit and start (1) for the next package

Especially step (2) can be quite complex (and very complex if you aren't as used to github and git - which applies I think to most devs). E.g. the removal of framework.secret in favor of the default in MicroKernelTrait requires a bit of searching on github to find. I've seen multiple people already asking about this change on Slack.

The greatest solution would be to have an interactive update-recipes command, but I think that's a lot of work (i.e. a command that interates over every change and asks if you want to apply it, skip it or edit it, we can ultimately also use git blame and link to the related github PR here).

[7ochem]

Today I've started upgrading from 5.0 to 5.1. After composer changes, my Q&A test was broken over this deprecation notice:

Since symfony/dotenv 5.1: Passing a boolean to the constructor of "Symfony\Component\Dotenv\Dotenv" is deprecated, use "Dotenv::usePutenv()".

I remembered config/bootstrap.php is doing something with Dotenv and wanted to check the contents of bootstrap.php in Symony 5.1 (which I checked out through symfony/website-skeleton), but it was gone 😱

I searched "bootstrap.php" on the SymfonyDevs Slack and found a post by @javiereguiluz about composer sync-recipes. It would have been very nice if the Flex Composer plugin would have warned or informed me about possible recipes changes, just like the blue "What's next?" boxes you get after installing Symfony.

[javiereguiluz]

Just to add another example: in this discussion -> symfony/demo#1117 (comment) @wouterj mentioned the sync-recipes command to other person who, judging by their reaction, didn't know about it. So, let's try to raise awareness of this command.

[maxhelias]

@javiereguiluz I opened a PR some time ago to add an explanation section to update the symfony recipes here : symfony/symfony-docs#13320. With the many returns, I don't think this is enough.

Some idea on RFC #518 like Mention symfony:recipes:install while installing recipes would be realy nice to inform people when there are install Symfony. And mention composer recipes for any composer update to invite to check all recipes or composer recipes vendor/package individually depending on the updated packages