[meta] Make the <root>/composer.json file a working example

If a user runs composer install on the (naked) composer.json from the Drupal root, then there are a few files and directories that are missing once composer is done with its work.

First, missing folders where extensions & c. go:

• modules/
• sites/
• themes/
• profiles/

It is a feature that these are missing, as they will likely be managed by the user's customized composer.json file. There are some additional example files, and necessary files that are also missing, and must be obtained from Drupal by hand:

• example.gitignore
• .htaccess
• README.txt
• robots.txt
• index.php
• web.config

I have omitted a couple of recently-added dot-files that might be useful, but are not critical if forgotten. This list may vary over time as files may be added to the Drupal root.

For the sake of completeness, it would probably be a good idea to document in the composer.json "_readme" section what the expectations of the user are here. For most people, this is probably going to involve creating a vcs repository to commit composer.json and other necessary files.

Here's a rough example:

"_readme": [
  "This is an example file to show how a Drupal website can be managed via",
  "Composer. In order to do this, it is recommended that you set up a version",
  "control repository, and commit the following files to it:",
  "  - composer.json (this file)",
  "  - .htaccess",
  "  - index.php",
  "  - robots.txt",
  "  - web.config",
  "Add your site's modules, themes and profiles to the 'requires' section",
  "above.  You might wish to also commit your 'sites' folder to this repository",
  "or manage it separately using a Composer package."
]

Links to external articles with more complete documentation would also be handy. It is not necessary for the documentation to be perfect from the get-go, or cover all of the variations of any alternate technique anyone might dream up; one example scenario should be sufficient. Since customization of the composer.json file is the motivator for the predecessor of this issue, #1975220: Allow a Composer user to manage Drupal, modules, and PHP dependencies with a custom root composer.json, I think it's good to clearly document the recommended workflow for doing this, so that it is clear to all involved.

That looks easier -- I'll try it.

What about contrib modules? We have #2373203: [no patch] Take over ownership of drupal/drupal and drupal/core on Packagist for core; are we going to rely on #1886820: Packagist for Drupal Projects for contrib, or do we expect drupal.org infrastructure to somehow handle this?

Will the composer.json in drupal/drupal contain an installer-paths item, so that composer require drupal/project will route to the right place?

Does composer update also pull in changes from index.php, and other files in drupal.git? Does this update also preserve whatever projects have been places in the modules and themes directories? I presume yes for these; will test it later.

Clarifying that this is a meta issue, and adding #2380389: Use a single vendor directory in the root to the issue summary.

Note that I've recently published https://github.com/tstoeckler/drupal-core to Packagist as drupal/core: https://packagist.org/packages/drupal/core

So with the Composer Installers issue in, the root composer.json actually *is* a working example now.

I wasn't aware of this possibility otherwise I would have noted it earlier and also in the parent issue.

Of course, we should still have some sort of "official" repository and maintain that on Packagist, but the code is the same and for now it works all the same. So not sure what to do with this meta issue.

Well, agai, I agree that there should be official repositories. But the only one who could do any harm with the drupal/core package right now is me. And I think it's preferable for me to squat it than someone who maybe isn't even part of the Drupal community.

I'm sure Packagist will agree to swap ownership once there's an official Drupal account. Also, you can delete packages, and I assume you can then recreate packages with the same name, although I haven't tried that.

I think it's important to have things that actually work. Whether or not there ever will be an "official" Packagist and/or Github account for Drupal is out of the hands of core developers, that would have to be managed by the DA. Moving forward here can easily take half a year or longer, and I want to build sites with Composer now and make that as comfortable as possible.

Yes, I intend to maintain this repository until an official owner steps forward. I will keep it up to date on a best-effort basis, but I use it myself regularly, so it won't lag too far behind. And I will also always keep the repository pristine, I.e. include truely only the subtree split (but for the master branch, which is exists for doc purposes).

I have a cron job on my laptop that runs every hour and updates the repo, which in turn updates the packagist package. So the package is properly maintained, which in turn makes the composer.json "working", at least with my definition of that.

I think we can mark this fixed, no?

Yes! Awesome!

Maybe we need another issue -- or hijack this one -- for updating the drupal.org infrastructure to support this natively.

@greg.1.anderson: As far as I understand it that would be #2352091: Create (and maintain) a subtree split of Drupal core

@tstoeckler
Isn't it a bit early for "Fixed", considering that neither #2389811: Move all the logic out of index.php (again) nor #2380389: Use a single vendor directory in the root have landed, meaning that the logic-heavy index.php still needs to be changed?

I guess the point of #30/#32 is that, once all of the dependent issues described in the summary are fixed, then nothing further needs to be done in this issue, since composer.json is already in its final form. Given that, there's probably no point in holding this open just to serve as a meta-issue; we could always re-open it if some change in a dependent issue later requires a change to composer.json. Or just open a new issue.

Regardless, it's great that this is working now with the 3rd party repositories.

Sure, it depends on the definition of "working". But there's no harm in keeping this open for a bit longer. I don't really care, just wanted to clean up.

This should really be the parent: #2002304: [META] Improve Drupal's use of Composer, part 1

How about instead of doing this we just make Drupal use composer like a normal modern PHP project: #2432893: Make Compser DrupalWTF Go Away

Still not sure why we don't just have a root /vendor for both composer.json files. Also not sure why we need a 'working example' after the fashion of example.gitignore. Why not just have a working one?

Is this issue valid now that the root composer.json isn't an example but an actual working and used file?

I think it's CWF but I'll let someone else do that.

#2380389: Use a single vendor directory in the root

Yes, let's close this one. It actually works now. We can still improve a couple other things, but the scope of this issue is fixed now.

Whop Whoop