Allow a user-editable composer.json file in Drupal's root directory to manage (custom) dependencies

Problem/Motivation

Site Maintainers ought to be able to utilize custom dependencies in their Drupal projects.
These dependencies could be:

1. Composer package such as Guzzle OAuth Subscriber
2. Drupal module such as Insert Field.
3. Drupal theme such as Omega
4. Drupal site such as davidwbarratt

All of these things (plus anything else that can be managed with Composer) should be able to be managed withing a Drupal Project, as if it were any other PHP project. Since Composer handles dependencies recursively, any of the above mentioned dependencies could have dependencies of their own and these will be managed within the same instance of Composer.

Since Drupal's composer.json file is in the root directory (which is far better than it being in the core directory), the question has been raised: Is it acceptable to modify Drupal's composer.json file?

This is an important question, however, it appears that the Drupal best practice of never modifying core still remains true.

In naderman& RobLoach's presentation at DrupalCon Munich, it was recommended that Drupal core become a dependency of Drupal. This would allow end-users to modify Drupal's composer.json file, while at the same time maintaining Drupal core's own composer.json file that would not be touched.

Proposed resolution

1. Essentially revert #1805316: Move composer.json to the project root
2. Create a new composer.json file in the project root
3. #2372815: Make the <root>/composer.json file a working example
4. Document how to use Composer with Drupal (i.e. modify index.php and change vendor directory)

The <root>/composer.jsonname will be:
drupal/drupal

The core/composer.jsonname will be:
drupal/core

The <root>/composer.json file would only have one requirement: drupal/core and the type would change to project

Pros

1. Users can use Composer without modifying a core file.
2. Drupal Core is a dependency of the Drupal project
3. Drupal's dependencies remain in-tact.
4. Composer users can exclude core and vendor directories from their repositories
5. Allows users to manage contrib modules via Composer (like #1886820: Packagist for Drupal Projects)
6. Only requires changes to two json files.
7. Does not require rewritting all current patches
8. Does not require any changes to the packaging script
9. Allows the core/vendor directory to remain in Drupal's repositories
10. Changes should be transparent to all users, minor changes for core maintainers.

Cons

1. Disruption: Drupal hosts may want/need to re-work their hosting platforms for Drupal 8 (to take advantage of this). This is also a benefit?
2. <root>/composer.json file is a non-working example until #2372815: Make the <root>/composer.json file a working example is resolved
3. Executing composer install from the root of the project would delete the core directory and add it back. Any changes to the folder would be destoryed.
4. Composer users will need to modify index.php in order to use Composer with Drupal.

Remaining tasks

1. Test the most recent patch
2. #2372815: Make the <root>/composer.json file a working example
3. Document how to use Composer with Drupal (i.e. modify index.php and change vendor directory)

Testing

You can test the most recent patch by:

1. Modify the example <root>/composer.json.
   1. Add this repository:
      {
  "type": "vcs",
  "url": "git@github.com:davidbarratt/drupal-core.git"
}

      Not necessary when/if #2372815: Make the <root>/composer.json file a working example lands.

   2. Require this custom installer
      
      "davidbarratt/custom-installer": "~1.0"

      Not necessary when/if #2372815: Make the <root>/composer.json file a working example lands.

   3. Add the necessary config for the custom installer in extra
      
      "custom-installer": {
  "drupal-core": "core"
}

      Not necessary when/if #2372815: Make the <root>/composer.json file a working example lands.

   For your conveince I've compiled all of these changes into this composer.json file.

2. Modify index.php
   Change this line from:
   $autoloader = require_once __DIR__ . '/core/vendor/autoload.php';

   to:

   $autoloader = require_once __DIR__ . '/vendor/autoload.php';

   Not necessary when/if #2380389: Change index.php to use a vendor directory in the root or move code out of index.php and into core lands.

API changes

Core contributors will need to change their working directory to /core before executing a composer command. However, this is the same as it was before #1805316: Move composer.json to the project root.