Make Composer create-project As Lean As Possible (ALAP)

I support this effort 100%. I have tried to do the same in the documentation for the updating Drupal with Composer, but people tend to add fixes for all special cases that often isn't relevant very long.

We should update the issue summary with links to the most relevant documentation page(s).

Absolutely agree on ALAP. Closely related situations should be properly documented. Other stuff should find its way to Troubleshooting Composer for Drupal site.

As the create-project downloads dependencies and default configuration is auto for deciding on source or dist, that should document you might want to remove .git when not doing code development. It causes issues when deploying your site with git. Or prevent it by https://getcomposer.org/doc/06-config.md#preferred-install or --prefer-dist. Very much dislike the language used in IS. It suggests poor understanding and doesn't inform properly.

Sorry, could you explain what "IS" refers to in

Very much dislike the language used in IS.

I just don't get it ;-)

Make sure there are no conflicts, lingering .git folders, etc. when running composer create-project which will result in a prompt, by creating a test which runs composer create-project with no options. The command should go straight through, without Composer presenting a "Keep/Yes/No/Always" prompt.

The reason Composer does this is not up to Composer, and is really out of scope for the Composer initiative.

It happens because sometimes the dependency needed by Drupal core is one that Composer defaults to using a git repo to provide.

The *solution* to that problem is to add --prefer-dist. That's why it's currently documented that way: A new user can just copy what the documentation says (currently using --prefer-dist), and hit the fewest roadblocks while also getting the most instructive errors worth taking to a slack channel or something.

In the general spirit of this issue, I've added some related issues dealing with the various roadblocks.

Referring to

We might want to add a note below: "NOTE: If for some reason you get a cryptic Composer "Keep/Yes/No/Aways" prompt, perhaps due to some left over .git folders, try adding --prefer-dist at the end of the command".

in `Proposed resolution`.

The usage of --prefer-dist should be documented and also point to the config option preferred-install. It shouldn't be in a `Note` as it is not something special.

The usage doesn't address everything and every possible situation. As you can see in the symfony/console documentation the order of options and parameters are not relevant. Only the order within the parameters are relevant. So, it is very much allowed to add options at the end. Very convenient when using options like --dry-run, --no-install, --no-update, -v, -vv, -vvv, --profile. Much easier to swap those options when they are at the end of the command.

Disagree on being out of scope of the Composer initiative, it should be in scope. It is ok not being in phase 1, needs to be addressed in later phases.

Disagree on being out of scope of the Composer initiative, it should be in scope. It is ok not being in phase 1, needs to be addressed in later phases.

Ok, we're talking about this sentence from the IS:

Make sure there are no conflicts, lingering .git folders, etc. when running composer create-project which will result in a prompt, by creating a test

1) Excellent idea to have a test that builds the project. That issue is here: #3086644: LegacyProject composer templates wrongly reference 8.x + fix test coverage

2) Having a .git folder in a dependency in the vendor folder isn't a problem. In fact, that's just how you get some packages that you might need.

In the past, Drupal core has sometimes tied its needs on a specific commit of an external package (drupal/coder comes to mind). A package with a version like that can't be installed any other way than using a repo.

This would not be a UX issue at all, because normally Composer will just remove the repo if it needs to. But we in Drupal-world have the drupal/core-vendor-hardening plugin (and previously the vendor cleanup script) which modifies repos by deleting their test directories (for security reasons). Because we modify repos in the vendor directory, Composer then asks the user about it whenever it needs to change things. If our plugin hadn't modified it, Composer would just remove it.

So, in that case, Drupal core had specific dependency needs for drupal/coder, and users had specific site security needs, and that combination yielded a UX that was less than idea because that's just how Composer works. All as a consequence of allowing the vendor directory in the docroot. :-) One way to never, ever see that modified-git prompt is to use --no-interaction, which is generally a not-great solution. Or don't use drupal/core-vendor-hardening, which leaves you open to SA-CORE-2017-001. Note that drupal/recommended-project doesn't use that plugin, since it stores vendor/ outside the docroot.

It's entirely within the scope of the Composer Initiative to do all the things that reduce the headache factor of Drupal and Composer. And also to make sure the documentation is readable, and honor the Principle of Least Surprise. But it's not within the scope of the Composer Initiative to make sure that Composer never prompts you. It's the kind of promise no one can make.

It's entirely within the scope of the Composer Initiative to do all the things that reduce the headache factor of Drupal and Composer. And also to make sure the documentation is readable, and honor the Principle of Least Surprise. But it's not within the scope of the Composer Initiative to make sure that Composer never prompts you. It's the kind of promise no one can make.

Couldn't agree more, very well formulated. Thanks for elaborating.

I removed the `--prefer-dist` option from the page Using Composer to Install Drupal and Manage Dependencies.

@ressa: Well, it's a little complicated.

The options that are specified at `create-project` are used to select the version of drupal/recommended-project that will be downloaded. After the first run, the settings from whatever is inside the composer.json from the downloaded project. The actual behavior of Composer is a little confusing. Let's break it down with an example.

Suppose you run composer create-project drupal/recommended-project --prefer-source today (at the time this comment was written).

1. Compose selects version 8.8.1 of drupal/recommended-project
2. prefer-dist is in the composer.json of drupal/recommended-project, but the --prefer-source option on the command line takes precedence, so you end up with sources (pulled from git) in your vendor directory
3. If you later run composer update, there's still prefer-source in the top-level composer.json file, but Composer remembers that --prefer-source was in effect when the vendor directory was composed, so no packages are changed (you still have sources)
4. If you remove vendor and run composer install, then Composer will use the prefer-source from the top-level composer.json file, and you will get dist (downloaded tarballs) packages in your vendor directory

This is all a little complicated for an introductory document, so I thought it was better to gloss over the details and just advise folks to fall back on the default behavior.