clarify what "dev" means in the composer installation instructions

Thanks for the issue! I'm not sure we need to clarify all of the options, but we could put in some of the explanation. Or maybe we could just say something like:

If you want to learn about what the command options mean, enter the command

composer help create-project

at the command line.

What you're implying about development releases is also relevant -- we might consider changing the --stability option to something other than "dev" for the User Guide. I am not sure what the stability options are actually... Hmm... This web site
https://getcomposer.org/doc/03-cli.md
explains that the default minimum stability is "stable", so maybe we should consider leaving out the "--stability dev" option, so that a stable version of Drupal would be installed? For User Guide readers, that would probably make more sense.

We could also put in this link
https://getcomposer.org/doc/03-cli.md#create-project
to the docs for the create-project command, but I think maybe the command-line help is more certain to be available (URLs sometimes move).

The "--stability dev" means that you are asking to download the development version, not a stable release version. I think that for the User Guide, we should actually use stability "stable" (which is the default if the --stability option is left out entirely).

Here's a patch that changes the stability to "stable", adds a bit more information about what will be downloaded, and adds a short Expand Your Understanding section pointing you to Composer help. Thoughts?

From how I read https://getcomposer.org/doc/03-cli.md#create-project,

--stability (-s): Minimum stability of package. Defaults to stable.

means that dev-versions are allowed, not that the dev-version of core or modules is downloaded.

More info on what "--stability dev" means in The Special Case of the “dev” Stability Flag: Funtimes with Composer!.

I sometimes use dev-version in my Drupal 8 web sites, so I probably prefer "--stability dev". Leaving out developer-packages is taken care of by "--no-dev", right?

Hm. I don't think most readers of the User Guide want to download the cutting-edge development version of Drupal or modules. Wouldn't stability stable make sure that doesn't happen? Or perhaps --stability beta, so that we would allow beta and stable releases?

But the user has to actively choose to download a dev-version of a module, it won't happen by chance. In my opinion we should give people the freedom to choose themselves. Anyone, even someone just starting with Drupal can need or want to download a dev-version of a module. And if they try in a project initiated with "--stability stable", they won't be allowed to, and it won't be obvious why not.

So you're saying that if we put --stability stable in when we do a create-project, then later we cannot download a dev version of a module?

I did not know that.

If that is the case, we should redo this patch with stability dev in there, and explain why in the text. Thanks!

I only have very basic Composer experience, but it's my understanding, after reading the information on these two pages. I would recommend that you check out the two links i included in #7, and verify that I have understood the information correctly :-)

If minimum-stability is set to beta or higher in your composer.json, you must explicitly whitelist individual projects for which you want to use a dev release by adding the @dev flag to its version constraint.

From https://blog.kalamuna.com/news/special-case-dev-stability-flag-funtimes-...

This is from the composer.json in a Drupal 8 project I initiated with composer create-project drupal-composer/drupal-project:8.x-dev some-dir --stability dev --no-interaction. With these settings I can still add dev-packages:

"minimum-stability": "dev",
"prefer-stable": true,

Ah, I see. When you do create-project, it creates the composer.json file that sets you up with the preferred stability level. That makes sense!

So, a new patch seems like a good idea. Thanks again for your help in understanding this!

You're welcome! And thank you for asking into it, I also gained a better understanding of Composer in the process.

I had a look at the patch in #6, and apart from what we agreed on (keeping --stability dev) the extra information about what will be downloaded and the bit about Composer help looks fine. One minor issue:

+. The latest stable version of the core software will be downloaded to the
+_mydir/web_ sub-directory, along with extra tools such as Drush and Drupal
+Console, but omitting the developer packages that are not used for production
+web sites.

Perhaps we should add the directory where Drush and Drupal Console are downloaded to. What do you think?

+. The latest stable version of the core software will be downloaded to the
+_mydir/web_ sub-directory, along with extra tools such as Drush and Drupal
+Console to _mydir/vendor_ sub-directory, but omitting the developer packages
+that are not used for production web sites.

I just tried with and without --stability dev and got identical stability settings in the composer.json files:

With --stability dev parameter
composer create-project drupal-composer/drupal-project:8.x-dev mydir-dev-stab --no-dev --no-progress --no-interaction --stability dev

composer.json:

    "minimum-stability": "dev",
    "prefer-stable": true,

---
Without --stability parameter
composer create-project drupal-composer/drupal-project:8.x-dev mydir-no-stab --no-dev --no-progress --no-interaction

composer.json:

    "minimum-stability": "dev",
    "prefer-stable": true,

---
--stability stable parameter doesn't work
I also tried with --stability stable which gave me this error:
composer create-project drupal-composer/drupal-project:8.x-dev mydir-dev --no-dev --no-progress --stability stable --no-interaction

Error:

[InvalidArgumentException]                                                   
Could not find package drupal-composer/drupal-project with version 8.x-dev.  

Thanks for asking a lot of really good questions about Composer and Drupal recently @alex.a. It only underlines that Composer is a hugely complex tool, which has made it quite hard to build Drupal 8 sites. I see it as the biggest obstacle for wider Drupal 8 adoption.

Even very experienced Drupal users like Joachim Noreiko (joachim) struggle with Composer, and find it a pain to use: Getting more than you bargained for: removing a Drupal module with Composer. Jeff Geerling has also struggled with Composer.

I don't see why the composer way of installing Drupal is installing Drush and Drupal Console, when the tarball does not, but that's another issue.

I agree, Drush and Drupal console should be included in Drupal core. But like you write, that's another discussion.

See this issue that asks for a separate deployment guide: https://github.com/drupal-composer/drupal-project/issues/373#issuecommen... This reinforces my view that this is a development tool, not a deployment tool.

I agree. I think a better model would be if module and core developers used Composer locally on their own machine to build modules and gather code from here and there, but that they should post a "complete" module to drupal.org, which could be downloaded and used right away, for example with Drush. External libraries which can't be included should be able to be downloaded with drush dl external_library_XYZ, or manually put in the correct folder. As I see it, a Drupal site builder shouldn't need to know that a tool like Composer even exists.

I think your question will get more views and answers if you post it at https://github.com/drupal-composer/drupal-project/, since only 4 people subscribe to this issue -- you, me and jhodgdon :-)

@alex.a that sounds interesting. I am looking forward to see if it would work with fx Search API Solr, see #2891694: Search API Solr - Add Ludwig integration.

@alex.a Interesting to see your plan for providing Ludwification. Sorry to hear that to be a composer plugin. Would be more helpful as extension to Ludwig module for Drupal itself.

Off topic, I know, do you have a place to discuss?

Regarding #14, that github project is the only currently working way of installing Drupal via Composer and ending up with a usable site that you can continue to use Composer with (see prior issues in this project for more details), and it includes Drush and Console, so that is what we get... at least until Core fixes the problems it has (as mentioned in the above comments).

Anyway. It looks like we don't need --stability at all, and that simplifies things for our users.

So... all of the above considered, here's a new patch. It's a small patch so I didn't make an interdiff (which would have been about as big as the patch itself).

Thanks for all the comments and reviews and testing!

Hm. @hansfn commented on #3001626-5: Update Composer instructions and make sure they are linked to from other topics:

Unfortunately "webflo/drupal-core-require-dev" is required even if we install Drupal using Composer create-project using "--no-dev". (It's actually not clear to me why, and composer "composer prohibits" doesn't report a problem. Weird. I tested several times.)

So ... do we need that here? What happens if we don't have it?

The "webflo/drupal-core-require-dev" bit is only used for updating, I believe. It is only mentioned in the Updating Drupal Core section here: https://github.com/drupal-composer/drupal-project#updating-drupal-core

For now, it seems like "--stability dev" is not needed, but we should try to keep an eye on composer.json, and check if the "--stability dev" parameter is needed again at some point. The patch looks good to me, great work!

OK, I'll go over to the other issue to discuss the webflo thing... thanks for the reviews! I'll get this committed sometime soon.

The option `--stability dev` refers to the picking of the package version when a non discrete version constraint is provided.
So: composer create-project drupal-composer/drupal-project myfolder -stability dev
It is required here because no version is provided and it defaults to stable which doesn't exist.
composer create-project drupal-composer/drupal-project myfolder 8.x-dev
No need here, 8.x-dev is a discrete value.
or even: composer create-project drupal-composer/drupal-project:8.x-dev myfolder
works without --stablity, a more common way to name a package.
Packages that release stable versions don't need a version unless you want a particular one, nor do they need the --stability option unless you want a different version than the latest stable.

Also drupal-composer/drupal-project is not the only package that works! All drupal distributions for D8 provide a package for composer to install their distribution. Not all distributions provide stable packages named after the drupal/core version.

The --no-dev applies to the project top level by default. There are plugins that import sub level json files (wikimedia/composer-merge-plugin). They are configurable to what gets imported. Expect the option to be respected depending on configuration.
For simple project suggest:
composer create-project "package" --no-install
composer remove "undesired like require-dev, drupal-console and drush" --no-update
composer install

Consider --no-interaction a convenience feature, similar to --verbose (-vvv) to be used when desired.

Currently there are plans to move drupal-composer/drupal-project into core. Even multiple so users can pick the project organization they like (flat folder like drupal/drupal or project folder above docroot). Assuming they'll change the namespace to drupal with project names according to organization. Or they might go for the easy way and let users copy such a template and issue the `composer create-project` in the target folder.

Hm, looking at the discussion in this issue, some clarification was clearly needed ;-) I assume everything is mostly clear to people now? Maybe the issue summary should be updated so coming readers don't need to read all the comments before understanding what the dev means ;-)

The patch looks good, but as I commented other places: I don't think we should recommend special versions of all commands in the User Guide just to avoid dev packages. It is confusing and it's so easy to get the dev packages installed by accident - either when you require a new package or if you use the wrong update command.

Composer supports environment variables and config settings. Unfortunately, the one useful to us is missing. That means the best way to avoid them is to make sure require-dev is empty and the merge plugin is configured with merge-dev as false.

--no-dev and --update-no-dev are the options to use on the cmdline (shows that drupal is not the only one with poor interface design!).

Let's merge this in with #3001626: Update Composer instructions and make sure they are linked to from other topics