[DX] Standarized installation instructions for bundles

[raulfraile]

During its lifetime, Symfony 2 has had two ways to install bundles: bin/vendors.php and Composer. And probably there will be another way to do it in the near future via the bundle:install command. Also, using Composer, there are several ways to do it: composer require, edit composer.json, .phar/no .phar...

For bundle maintainers this is a problem, and from the point of view of the developer, can be confusing that instructions change from one bundle to another.

Proposal: Add a section in the symfony official documentation where, based on the Symfony version, provides all the instructions and alternatives to install any bundle. Then, the bundle maintainers can link to that page in our docs.

[javiereguiluz]

👍 it's really confusing to get different instructions depending upon the creator of the bundle.

Modern bundles always tell you to just execute one command:

$ cd your-project/
$ composer require vendor/bundle "~N.N"

But most of the existing bundles tells you to edit your composer.json file and then update your dependencies with composer update, which is a mistake because that updates ALL of your dependencies.

So, what do you guys think about promoting (not forcing) to use the cool composer require way of installing bundles for modern Symfony versions?

Regarding the instructions for outdated Symfony versions, such as 2.0, I know that it looks like the effort it's not worth it. But keep in mind that we just need to write a pair of paragraphs about this and for historical reasons, it could be useful.

[merk]

Some installation instructions use @stable as the version constraint but advise about replacing this with actual versions.

I prefer npm's method where it will just pull in the latest version if a version is not specified. It kind of removes the need for maintaining version numbers in all the bundle readmes.

[stof]

Regarding the instructions for outdated Symfony versions, such as 2.0, I know that it looks like the effort it's not worth it. But keep in mind that we just need to write a pair of paragraphs about this and for historical reasons, it could be useful.

IMO, it is not. Most bundles are not compatible with 2.0 anymore. Supporting 2.0 alongside 2.1 is already a pain, and supporting 2.0 and 2.3+ is impossible without huge hacks (I mean in a single version of the bundle)

[stof]

Some installation instructions use @stable as the version constraint but advise about replacing this with actual versions.

this is a bad idea, because @stable is an unbound constraint (it does not prevent jumping to the next master version when it becomes stable

I prefer npm's method where it will just pull in the latest version if a version is not specified. It kind of removes the need for maintaining version numbers in all the bundle readmes.

There is a proposal to make composer require generate the constraint based on the available versions on Packagist when you don't specify it. It may be merged in the future

[merk]

Yeah - I realise @stable is not appropriate for composer.json - but composer require could resolve that to ~1.2.3.

[weaverryan]

+1 to using "require". And I think we should make an effort to actually go through the docs for the most popular bundles and help make the docs consistent.

And if we can get composer/composer#3096 merged, then you'll be able to safely run php composer.phar require acme/my-lib only and have it select the latest version with a nice ~1.2.1-style constraint in composer.json. That PR is ready, I'm just waiting on someone to merge it.

[weaverryan]

... and then with a bundle:install style command (symfony/symfony-standard#695), we'd be in really good shape.

[raulfraile]

I think we all agree on promoting the use of composer require on third-party bundles docs, and once bundle:install is ready, make that the default choice. The question now would be, do we add it as a guideline in the bundles best practices page or centralize it somehow so bundles can link to it?

[javiereguiluz]

@raulfraile I guess that it would depend on how much do we want to explain about this. If it's just one or two paragraphs, maybe it's better to include it directly in the bundles' best practices page.

[javiereguiluz]

@weaverryan @wouterj @xabbuh in my opinion this is a very high priority issue because of this:

• The amount of work to do is really small (just a few lines of documentation)
• The impact for end users could be huge (imagine all bundles with standardized and simple installation instructions!)
• This is a great candidate for the DX Hackday of tomorrow (if we add the documentation today, people can start improving the bundles installation instructions as part of the Hackday. Even inexperienced Symfony developers can do that!)

[raulfraile]

@javiereguiluz 👍 I think exactly the same. It could have a great impact for end users, lowers the entry barrier for beginners and lots of bundles could get tomorrow PRs in the hackday to update the docs

[xabbuh]

@javiereguiluz I'm not sure if I fully understood what you would like to see in the docs. Is it to mention that one should provide installation instructions for users? These would basically be something like:

Use Composer's require command to install the bundle:

composer require acme/demo-bundle version

[javiereguiluz]

@xabbuh that's precisely the idea! To have something ultra-simple that can be mentioned as "the official Symfony recommendation for installing bundles". That will allow us to makes tens of PR to improve and standardize installation instructions across the Symfony ecosystem.

Anyway, to the documentation that you propose, I'd add:

• Some comment about having Composer installed globally, which is the recommendation for professional developers (ideally with a link to the simple instructions to achieve that ... which are the same that you can find in symfony.com/download)
• Some comment about how to indicate the version constraint (avoid using @stable, enclose it with quotes to get 100% support across different shells, etc.)
• Any other idea that we can imagine.

In any case, everything would be much better if someone prepares a PR and we can add comments to it.