10000 Improve discoverability of recipe changes · Issue #629 · symfony/flex · GitHub
[go: up one dir, main page]
Skip to content

Improve discoverability of recipe changes #629

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed 8000
javiereguiluz opened this issue Jun 5, 2020 · 23 comments
Closed

Improve discoverability of recipe changes #629

javiereguiluz opened this issue Jun 5, 2020 · 23 comments

Comments

@javiereguiluz
Copy link
Member

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
Copy link
Member

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

@javiereguiluz
Copy link
Member Author

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
Copy link
pbowyer commented Jun 5, 2020

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
Copy link
Amunak commented Jun 5, 2020

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
Copy link
ahundiak commented Jun 5, 2020 •
edited
Loading

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
Copy link
Member
stof commented Jun 5, 2020

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
Copy link

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
Copy link
Contributor
maxhelias commented Jun 8, 2020 •
edited
Loading

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

@maxhelias
Copy link
Contributor

@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
Copy link
Member
wouterj commented Jun 8, 2020 •
edited
Loading

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
Copy link
7ochem commented Jun 11, 2020 •
edited
Loading

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
Copy link
Member Author

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
Copy link
Contributor

@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

@javiereguiluz javiereguiluz mentioned this issue Jun 11, 2020
Closed
@maxhelias maxhelias mentioned this issue Jun 14, 2020
Merged
@elkuku
Copy link
elkuku commented Jul 19, 2020

I think it would be cool if composer outdated would also show a list of outdated recipes 😉

@stof
Copy link
Member
stof commented Jul 23, 2020

I don't think hacking existing composer command to make them show more stuff is a good idea:

  • it makes things much harder to maintain (as changes in composer might break the plugin if we don't rely on expected plugin extension points)
  • it can break existing tooling relying on running composer outdated command if we add more stuff in the output.

@7ochem
Copy link
7ochem commented Jul 23, 2020

@stof This is a good argument against, for example @elkuku 's idea of making composer outdated show a list of outdated recipes as this needs a lot of integration with Composer itself and checks on versions.

Your argument does not hold, in my opinion, to just showing a simple information box. Just like the boxes shown after creating a new Symfony project ("What's next?")

@stof
Copy link
Member
stof commented Jul 23, 2020

even an info box could mess the tooling processing the output of the command

@stof
Copy link
Member
stof commented Jul 23, 2020

and there is also not an official extension point to insert extra output at the end of the composer outdated command, so just showing this info box would require the same level of hacky integration.

@7ochem
Copy link
7ochem commented Jul 23, 2020

I did not mean composer outdated specifically. I understand that the information of such command could be processed by some tooling.

maxhelias commented on Jun 8

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

@maxhelias
Copy link
Contributor

@elkuku, @7ochem you can use composer recipes this is the same as composer outdated but only for recipes

And I have submit a PR to display this information on each composer update or composer install : #633

nicolas-grekas added a commit that referenced this issue Aug 25, 2020
@nicolas-grekas
minor #633 Improve discoverability of 'composer recipes' (maxhelias)
daa5ab6 
This PR was merged into the 1.8-dev branch.

Discussion
----------

Improve discoverability of 'composer recipes'

Discovering the `composer recipes` command during composer install/update

Fix issue #629 and move forward #518 - 8)

![Capture d’écran 2020-06-15 à 17 05 28](https://user-images.githubusercontent.com/12966574/84673799-77b41800-af2a-11ea-9a64-751aa78fde83.png)

Commits
-------

eae35f1 Improve discoverability of 'composer recipes'
tgalopin pushed a commit to tgalopin/flex that referenced this issue Dec 3, 2020
Merge pull request symfony#629
9126fd7
@gggeek gggeek mentioned this issue Feb 26, 2021
Closed
@maxhelias
Copy link
Contributor

I think we can close this issue. The Symfony docs is updated : symfony/symfony-docs#13320 and a warning is displayed on each composer update or composer install with #633.

However, we should keep #575 to improve the following page https://symfony.com/doc/5.3/quick_tour/flex_recipes.html
8000

@wouterj
Copy link
Member
wouterj commented Mar 29, 2021

I think #629 (comment) still applies

@weaverryan
Copy link
Member

I think this will be solved by #845. In addition to the new recipes:update command performing a true diff update (so it's easy to see what REALLY changed, whereas before it completely replaced your file, so the diff was complex), it also generates a CHANGELOG for you of all the PR's that contributed to the changes :).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
0