splitting up some docs, closes #4155

doc/04-schema.md

@@ -272,7 +272,7 @@ Example:
 
 All links are optional fields.
 
-`require` and `require-dev` additionally support stability flags (root-only).
+`require` and `require-dev` additionally support stability flags ([root-only](04-schema.md#root-package)).
 These allow you to further restrict or expand the stability of a package beyond
 the scope of the [minimum-stability](#minimum-stability) setting. You can apply
 them to a constraint, or just apply them to an empty constraint if you want to
@@ -335,7 +335,7 @@ aliases article](articles/aliases.md).
 Lists packages required by this package. The package will not be installed
 unless those requirements can be met.
 
-#### require-dev <span>(root-only)</span>
+#### require-dev <span>([root-only](04-schema.md#root-package))</span>
 
 Lists packages required for developing this package, or running
 tests, etc. The dev requirements of the root package are installed by default.
@@ -555,7 +555,7 @@ Example:
 }
 ```
 
-### autoload-dev <span>(root-only)</span>
+### autoload-dev <span>([root-only](04-schema.md#root-package))</span>
 
 This section allows to define autoload rules for development purposes.
 
@@ -628,7 +628,7 @@ To do that, `autoload` and `target-dir` are defined as follows:
 
 Optional.
 
-### minimum-stability <span>(root-only)</span>
+### minimum-stability <span>([root-only](04-schema.md#root-package))</span>
 
 This defines the default behavior for filtering packages by stability. This
 defaults to `stable`, so if you rely on a `dev` package, you should specify
@@ -643,7 +643,7 @@ a given package can be done in `require` or `require-dev` (see
 Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`,
 and `stable`.
 
-### prefer-stable <span>(root-only)</span>
+### prefer-stable <span>([root-only](04-schema.md#root-package))</span>
 
 When this is enabled, Composer will prefer more stable packages over unstable
 ones when finding compatible stable packages is possible. If you require a
@@ -652,7 +652,7 @@ selected granted that the minimum-stability allows for it.
 
 Use `"prefer-stable": true` to enable.
 
-### repositories <span>(root-only)</span>
+### repositories <span>([root-only](04-schema.md#root-package))</span>
 
 Custom package repositories to use.
 
@@ -731,194 +731,4 @@ will look from the first to the last repository, and pick the first match.
 By default Packagist is added last which means that custom repositories can
 override packages from it.
 
-### config <span>(root-only)</span>
-
-A set of configuration options. It is only used for projects.
-
-The following options are supported:
-
-* **process-timeout:** Defaults to `300`. The duration processes like git clones
-  can run before Composer assumes they died out. You may need to make this
-  higher if you have a slow connection or huge vendors.
-* **use-include-path:** Defaults to `false`. If true, the Composer autoloader
-  will also look for classes in the PHP include path.
-* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or
-  `auto`. This option allows you to set the install method Composer will prefer to
-  use.
-* **store-auths:** What to do after prompting for authentication, one of:
-  `true` (always store), `false` (do not store) and `"prompt"` (ask every
-  time), defaults to `"prompt"`.
-* **github-protocols:** Defaults to `["git", "https", "ssh"]`. A list of protocols to
-  use when cloning from github.com, in priority order. You can reconfigure it to
-  for example prioritize the https protocol if you are behind a proxy or have somehow
-  bad performances with the git protocol.
-* **github-oauth:** A list of domain names and oauth keys. For example using
-  `{"github.com": "oauthtoken"}` as the value of this option will use `oauthtoken`
-  to access private repositories on github and to circumvent the low IP-based
-  rate limiting of their API.
-  [Read more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
-  on how to get an OAuth token for GitHub.
-* **http-basic:** A list of domain names and username/passwords to authenticate
-  against them. For example using
-  `{"example.org": {"username": "alice", "password": "foo"}` as the value of this
-  option will let composer authenticate against example.org.
-* **platform:** Lets you fake platform packages (PHP and extensions) so that
-  you can emulate a production env or define your target platform in the
-  config. e.g. `{"php": "5.4", "ext-something": "4.0"}`.
-* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a
-  different directory if you want to. `$HOME` and `~` will be replaced by your
-  home directory's path in vendor-dir and all `*-dir` options below.
-* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they
-  will be symlinked into this directory.
-* **cache-dir:** Defaults to `$COMPOSER_HOME/cache` on unix systems and
-  `C:\Users\<user>\AppData\Local\Composer` on Windows. Stores all the caches
-  used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home).
-* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives
-  of packages.
-* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata
-  for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`.
-* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for
-  loading VCS repository metadata for the `git`/`hg` types and to speed up installs.
-* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all
-  dist (zip, tar, ..) packages that it downloads. Those are purged after six
-  months of being unused by default. This option allows you to tweak this
-  duration (in seconds) or disable it completely by setting it to 0.
-* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all
-  dist (zip, tar, ..) packages that it downloads. When the garbage collection
-  is periodically ran, this is the maximum size the cache will be able to use.
-  Older (less used) files will be removed first until the cache fits.
-* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader
-  will not be prepended to existing autoloaders. This is sometimes required to fix
-  interoperability issues with other autoloaders.
-* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for
-  the generated Composer autoloader. When null a random one will be generated.
-* **optimize-autoloader** Defaults to `false`. Always optimize when dumping
-  the autoloader.
-* **classmap-authoritative:** Defaults to `false`. If true, the composer
-  autoloader will not scan the filesystem for classes that are not found in
-  the class map. Implies 'optimize-autoloader'.
-* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in
-  github mode. This is used for GitHub Enterprise setups.
-* **github-expose-hostname:** Defaults to `true`. If set to false, the OAuth
-  tokens created to access the github API will have a date instead of the
-  machine hostname.
-* **notify-on-install:** Defaults to `true`. Composer allows repositories to
-  define a notification URL, so that they get notified whenever a package from
-  that repository is installed. This option allows you to disable that behaviour.
-* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or
-  `"stash"`. This option allows you to set the default style of handling dirty
-  updates when in non-interactive mode. `true` will always discard changes in
-  vendors, while `"stash"` will try to stash and reapply. Use this for CI
-  servers or deploy scripts if you tend to have modified vendors.
-* **archive-format:** Defaults to `tar`. Composer allows you to add a default
-  archive format when the workflow needs to create a dedicated archiving format.
-* **archive-dir:** Defaults to `.`. Composer allows you to add a default
-  archive directory when the workflow needs to create a dedicated archiving format.
-  Or for easier development between modules.
-
-Example:
-
-```json
-{
-    "config": {
-        "bin-dir": "bin"
-    }
-}
-```
-
-> **Note:** Authentication-related config options like `http-basic` and
-> `github-oauth` can also be specified inside a `auth.json` file that goes
-> besides your `composer.json`. That way you can gitignore it and every
-> developer can place their own credentials in there.
-
-### scripts <span>(root-only)</span>
-
-Composer allows you to hook into various parts of the installation process
-through the use of scripts.
-
-See [Scripts](articles/scripts.md) for events details and examples.
-
-### extra
-
-Arbitrary extra data for consumption by `scripts`.
-
-This can be virtually anything. To access it from within a script event
-handler, you can do:
-
-```php
-$extra = $event->getComposer()->getPackage()->getExtra();
-```
-
-Optional.
-
-### bin
-
-A set of files that should be treated as binaries and symlinked into the `bin-dir`
-(from config).
-
-See [Vendor Binaries](articles/vendor-binaries.md) for more details.
-
-Optional.
-
-### archive
-
-A set of options for creating package archives.
-
-The following options are supported:
-
-* **exclude:** Allows configuring a list of patterns for excluded paths. The
-  pattern syntax matches .gitignore files. A leading exclamation mark (!) will
-  result in any matching files to be included even if a previous pattern
-  excluded them. A leading slash will only match at the beginning of the project
-  relative path. An asterisk will not expand to a directory separator.
-
-Example:
-
-```json
-{
-    "archive": {
-        "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
-    }
-}
-```
-
-The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`,
-`/foo/my.test` but it will exclude `/foo/bar/any`, `/foo/baz`, and `/my.test`.
-
-Optional.
-
-### non-feature-branches
-
-A list of regex patterns of branch names that are non-numeric (e.g. "latest" or something), that will NOT be handled as feature branches. This is an array of strings.
-
-If you have non-numeric branch names, for example like "latest", "current", "latest-stable"
-or something, that do not look like a version number, then composer handles such branches
-as feature branches. This means it searches for parent branches, that look like a version
-or ends at special branches (like master) and the root package version number becomes the
-version of the parent branch or at least master or something.
-
-To handle non-numeric named branches as versions instead of searching for a parent branch
-with a valid version or special branch name like master, you can set patterns for branch
-names, that should be handled as dev version branches.
-
-This is really helpful when you have dependencies using "self.version", so that not dev-master,
-but the same branch is installed (in the example: latest-testing).
-
-An example:
-
-If you have a testing branch, that is heavily maintained during a testing phase and is
-deployed to your staging environment, normally "composer show -s" will give you `versions : * dev-master`.
-
-If you configure `latest-.*` as a pattern for non-feature-branches like this:
-
-```json
-{
-    "non-feature-branches": ["latest-.*"]
-}
-```
-
-Then "composer show -s" will give you `versions : * dev-latest-testing`.
-
-Optional.
-
 &larr; [Command-line interface](03-cli.md)  |  [Repositories](05-repositories.md) &rarr;

doc/05-repositories.md

@@ -616,4 +616,4 @@ You can disable the default Packagist repository by adding this to your
 }
 ```
 
-← [Schema](04-schema.md)  |  [Community](06-community.md) →
+← [Schema](04-schema.md)  |  [Config](06-config.md) →

doc/06-config.md

@@ -0,0 +1,195 @@
+# Config
+
+This chapter will describe the `config` section of the `composer.json` schema.
+
+### config <span>([root-only](04-schema.md#root-package))</span>
+
+A set of configuration options. It is only used for projects.
+
+The following options are supported:
+
+* **process-timeout:** Defaults to `300`. The duration processes like git clones
+  can run before Composer assumes they died out. You may need to make this
+  higher if you have a slow connection or huge vendors.
+* **use-include-path:** Defaults to `false`. If true, the Composer autoloader
+  will also look for classes in the PHP include path.
+* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or
+  `auto`. This option allows you to set the install method Composer will prefer to
+  use.
+* **store-auths:** What to do after prompting for authentication, one of:
+  `true` (always store), `false` (do not store) and `"prompt"` (ask every
+  time), defaults to `"prompt"`.
+* **github-protocols:** Defaults to `["git", "https", "ssh"]`. A list of protocols to
+  use when cloning from github.com, in priority order. You can reconfigure it to
+  for example prioritize the https protocol if you are behind a proxy or have somehow
+  bad performances with the git protocol.
+* **github-oauth:** A list of domain names and oauth keys. For example using
+  `{"github.com": "oauthtoken"}` as the value of this option will use `oauthtoken`
+  to access private repositories on github and to circumvent the low IP-based
+  rate limiting of their API.
+  [Read more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
+  on how to get an OAuth token for GitHub.
+* **http-basic:** A list of domain names and username/passwords to authenticate
+  against them. For example using
+  `{"example.org": {"username": "alice", "password": "foo"}` as the value of this
+  option will let composer authenticate against example.org.
+* **platform:** Lets you fake platform packages (PHP and extensions) so that
+  you can emulate a production env or define your target platform in the
+  config. e.g. `{"php": "5.4", "ext-something": "4.0"}`.
+* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a
+  different directory if you want to. `$HOME` and `~` will be replaced by your
+  home directory's path in vendor-dir and all `*-dir` options below.
+* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they
+  will be symlinked into this directory.
+* **cache-dir:** Defaults to `$COMPOSER_HOME/cache` on unix systems and
+  `C:\Users\<user>\AppData\Local\Composer` on Windows. Stores all the caches
+  used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home).
+* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives
+  of packages.
+* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata
+  for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`.
+* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for
+  loading VCS repository metadata for the `git`/`hg` types and to speed up installs.
+* **cache-files-ttl:** Defaults to `15552000` (6 months). Composer caches all
+  dist (zip, tar, ..) packages that it downloads. Those are purged after six
+  months of being unused by default. This option allows you to tweak this
+  duration (in seconds) or disable it completely by setting it to 0.
+* **cache-files-maxsize:** Defaults to `300MiB`. Composer caches all
+  dist (zip, tar, ..) packages that it downloads. When the garbage collection
+  is periodically ran, this is the maximum size the cache will be able to use.
+  Older (less used) files will be removed first until the cache fits.
+* **prepend-autoloader:** Defaults to `true`. If false, the composer autoloader
+  will not be prepended to existing autoloaders. This is sometimes required to fix
+  interoperability issues with other autoloaders.
+* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for
+  the generated Composer autoloader. When null a random one will be generated.
+* **optimize-autoloader** Defaults to `false`. Always optimize when dumping
+  the autoloader.
+* **classmap-authoritative:** Defaults to `false`. If true, the composer
+  autoloader will not scan the filesystem for classes that are not found in
+  the class map. Implies 'optimize-autoloader'.
+* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in
+  github mode. This is used for GitHub Enterprise setups.
+* **github-expose-hostname:** Defaults to `true`. If set to false, the OAuth
+  tokens created to access the github API will have a date instead of the
+  machine hostname.
+* **notify-on-install:** Defaults to `true`. Composer allows repositories to
+  define a notification URL, so that they get notified whenever a package from
+  that repository is installed. This option allows you to disable that behaviour.
+* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or
+  `"stash"`. This option allows you to set the default style of handling dirty
+  updates when in non-interactive mode. `true` will always discard changes in
+  vendors, while `"stash"` will try to stash and reapply. Use this for CI
+  servers or deploy scripts if you tend to have modified vendors.
+* **archive-format:** Defaults to `tar`. Composer allows you to add a default
+  archive format when the workflow needs to create a dedicated archiving format.
+* **archive-dir:** Defaults to `.`. Composer allows you to add a default
+  archive directory when the workflow needs to create a dedicated archiving format.
+  Or for easier development between modules.
+
+Example:
+
+```json
+{
+    "config": {
+        "bin-dir": "bin"
+    }
+}
+```
+
+> **Note:** Authentication-related config options like `http-basic` and
+> `github-oauth` can also be specified inside a `auth.json` file that goes
+> besides your `composer.json`. That way you can gitignore it and every
+> developer can place their own credentials in there.
+
+### scripts <span>(root-only)</span>
+
+Composer allows you to hook into various parts of the installation process
+through the use of scripts.
+
+See [Scripts](articles/scripts.md) for events details and examples.
+
+### extra
+
+Arbitrary extra data for consumption by `scripts`.
+
+This can be virtually anything. To access it from within a script event
+handler, you can do:
+
+```php
+$extra = $event->getComposer()->getPackage()->getExtra();
+```
+
+Optional.
+
+### bin
+
+A set of files that should be treated as binaries and symlinked into the `bin-dir`
+(from config).
+
+See [Vendor Binaries](articles/vendor-binaries.md) for more details.
+
+Optional.
+
+### archive
+
+A set of options for creating package archives.
+
+The following options are supported:
+
+* **exclude:** Allows configuring a list of patterns for excluded paths. The
+  pattern syntax matches .gitignore files. A leading exclamation mark (!) will
+  result in any matching files to be included even if a previous pattern
+  excluded them. A leading slash will only match at the beginning of the project
+  relative path. An asterisk will not expand to a directory separator.
+
+Example:
+
+```json
+{
+    "archive": {
+        "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
+    }
+}
+```
+
+The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`,
+`/foo/my.test` but it will exclude `/foo/bar/any`, `/foo/baz`, and `/my.test`.
+
+Optional.
+
+### non-feature-branches
+
+A list of regex patterns of branch names that are non-numeric (e.g. "latest" or something), that will NOT be handled as feature branches. This is an array of strings.
+
+If you have non-numeric branch names, for example like "latest", "current", "latest-stable"
+or something, that do not look like a version number, then composer handles such branches
+as feature branches. This means it searches for parent branches, that look like a version
+or ends at special branches (like master) and the root package version number becomes the
+version of the parent branch or at least master or something.
+
+To handle non-numeric named branches as versions instead of searching for a parent branch
+with a valid version or special branch name like master, you can set patterns for branch
+names, that should be handled as dev version branches.
+
+This is really helpful when you have dependencies using "self.version", so that not dev-master,
+but the same branch is installed (in the example: latest-testing).
+
+An example:
+
+If you have a testing branch, that is heavily maintained during a testing phase and is
+deployed to your staging environment, normally "composer show -s" will give you `versions : * dev-master`.
+
+If you configure `latest-.*` as a pattern for non-feature-branches like this:
+
+```json
+{
+    "non-feature-branches": ["latest-.*"]
+}
+```
+
+Then "composer show -s" will give you `versions : * dev-latest-testing`.
+
+Optional.
+
+&larr; [Repositories](05-repositories.md)  |  [Community](07-community.md) &rarr;

doc/06-community.md → doc/07-community.md

@@ -6,7 +6,9 @@ contributing.
 ## Contributing
 
 If you would like to contribute to composer, please read the
-[README](https://github.com/composer/composer).
+[README](https://github.com/composer/composer) and 
+[CONTRIBUTING](https://github.com//composer/composer/blob/master/CONTRIBUTING.md)
+documents.
 
 The most important guidelines are described as follows:
 
@@ -31,4 +33,4 @@ for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for developme
 Stack Overflow has a growing collection of
 [Composer related questions](https://stackoverflow.com/questions/tagged/composer-php).
 
-← [Repositories](05-repositories.md)
+← [Config](06-config.md)