Merge pull request #626 from igorw/notify-and-repo-docs

[docs] Notify, composer repository spec, COMPOSER_HOME, aliases

doc/02-libraries.md

@@ -76,6 +76,14 @@ Here are some examples of version branch names:
 > **Note:** When you install a dev version, it will install it from source.
 See [Repositories](05-repositories.md) for more information.
 
+### Aliases
+
+It is possible alias branch names to versions. For example, you could alias
+`dev-master` to `1.0-dev`, which would allow you to require `1.0-dev` in all
+the packages.
+
+See [Aliases](articles/aliases.md) for more information.
+
 ## Lock file
 
 For your library you may commit the `composer.lock` file if you want to. This

doc/03-cli.md

@@ -199,11 +199,6 @@ directory other than `vendor`.
 By setting this option you can change the `bin` ([Vendor Bins](articles/vendor-bins.md))
 directory to something other than `vendor/bin`.
 
-### COMPOSER_PROCESS_TIMEOUT
-
-This env var controls the time composer waits for commands (such as git
-commands) to finish executing. The default value is 60 seconds.
-
 ### http_proxy or HTTP_PROXY
 
 If you are using composer from behind an HTTP proxy, you can use the standard
@@ -215,4 +210,19 @@ some tools like git or curl will only use the lower-cased `http_proxy` version.
 Alternatively you can also define the git proxy using
 `git config --global http.proxy <proxy url>`.
 
+### COMPOSER_HOME
+
+The `COMPOSER_HOME` var allows you to change the composer home directory. This
+is a hidden, global (per-user on the machine) directory that is shared between
+all projects.
+
+By default it points to `/home/<user>/.composer` on *nix,
+`/Users/<user>/.composer` on OSX and
+`C:\Users\<user>\AppData\Roaming\Composer` on Windows.
+
+### COMPOSER_PROCESS_TIMEOUT
+
+This env var controls the time composer waits for commands (such as git
+commands) to finish executing. The default value is 300 seconds (5 minutes).
+
 &larr; [Libraries](02-libraries.md)  |  [Schema](04-schema.md) &rarr;

doc/04-schema.md

@@ -368,6 +368,9 @@ 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.
+* **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.
 
 Example:
 

doc/05-repositories.md

@@ -54,15 +54,24 @@ want to learn why.
 ### Composer
 
 The main repository type is the `composer` repository. It uses a single
-`packages.json` file that contains all of the package metadata. The JSON
+`packages.json` file that contains all of the package metadata.
-format is as follows:
+
+This is also the repository type that packagist uses. To reference a
+`composer` repository, just supply the path before the `packages.json` file.
+In case of packagist, that file is located at `/packages.json`, so the URL of
+the repository would be `packagist.org`. For `example.org/packages.json` the
+repository URL would be `example.org`.
+
+#### packages
+
+The only required field is `packages`. The JSON structure is as follows:
 
     {
-        "vendor/packageName": {
+        "packages": {
-            "name": "vendor/packageName",
+            "vendor/packageName": {
-            "description": "Package description",
-            "versions": {
                 "master-dev": { @composer.json },
+                "1.0.x-dev": { @composer.json },
+                "0.0.1": { @composer.json },
                 "1.0.0": { @composer.json }
             }
         }
@@ -88,12 +97,54 @@ Here is a minimal package definition:
 
 It may include any of the other fields specified in the [schema](04-schema.md).
 
-The `composer` repository is also what packagist uses. To reference a
+#### notify
-`composer` repository, just supply the path before the `packages.json` file.
+
-In case of packagist, that file is located at `/packages.json`, so the URL of
+The `notify` field allows you to specify an URL template for a URL that will
-the repository would be `http://packagist.org`. For
+be called every time a user installs a package.
-`http://example.org/packages.json` the repository URL would be
+
-`http://example.org`.
+An example value:
+
+    {
+        "notify": "/downloads/%package%"
+    }
+
+For `example.org/packages.json` containing a `monolog/monolog` package, this
+would send a `POST` request to `example.org/downloads/monolog/monolog` with
+following parameters:
+
+* **version:** The version of the package.
+* **version_normalized:** The normalized internal representation of the
+  version.
+
+This field is optional.
+
+#### includes
+
+For large repositories it is possible to split the `packages.json` into
+multiple files. The `includes` field allows you to reference these additional
+files.
+
+An example:
+
+    {
+        "includes": {
+            "packages-2011.json": {
+                "sha1": "525a85fb37edd1ad71040d429928c2c0edec9d17"
+            },
+            "packages-2012-01.json": {
+                "sha1": "897cde726f8a3918faf27c803b336da223d400dd"
+            },
+            "packages-2012-02.json": {
+                "sha1": "26f911ad717da26bbcac3f8f435280d13917efa5"
+            }
+        }
+    }
+
+The SHA-1 sum of the file allows it to be cached and only re-requested if the
+hash changed.
+
+This field is optional. You probably don't need it for your own custom
+repository.
 
 ### VCS
 

doc/articles/aliases.md

@@ -0,0 +1,90 @@
+<!--
+    tagline: Alias branch names to versions
+-->
+# Aliases
+
+## Why aliases?
+
+When you are using a VCS repository, you will only get comparable versions for
+branches that look like versions, such as `2.0`. For your `master` branch, you
+will get a `dev-master` version. For your `bugfix` branch, you will get a
+`dev-bugfix` version.
+
+If your `master` branch is used to tag releases of the `1.0` development line,
+i.e. `1.0.1`, `1.0.2`, `1.0.3`, etc., any package depending on it will
+probably require version `1.0.*`.
+
+If anyone wants to require the latest `dev-master`, they have a problem: Other
+packages may require `1.0.*`, so requiring that dev version will lead to
+conflicts, since `dev-master` does not match the `1.0.*` constraint.
+
+Enter aliases.
+
+## Branch alias
+
+The `dev-master` branch is one in your main VCS repo. It is rather common that
+someone will want the latest master dev version. Thus, Composer allows you to
+alias your `dev-master` branch to a `1.0.x-dev` version. It is done by
+specifying a `branch-alias` field under `extra` in `composer.json`:
+
+    {
+        "extra": {
+            "branch-alias": {
+                "dev-master": "1.0.x-dev"
+            }
+        }
+    }
+
+The branch version must begin with `dev-` (non-comparable version), the alias
+must be a comparable dev version. The `branch-alias` must be present on the
+branch that it references. For `dev-master`, you need to commit it on the
+`master` branch.
+
+As a result, you can now require `1.0.*` and it will happily install
+`dev-master` for you.
+
+## Require inline alias
+
+Branch aliases are great for aliasing main development lines. But in order to
+use them you need to have control over the source repository, and you need to
+commit changes to version control.
+
+This is not really fun when you just want to try a bugfix of some library that
+is a dependency of your local project.
+
+For this reason, you can alias packages in your `require` and `require-dev`
+fields. Let's say you found a bug in the `monolog/monolog` package. You cloned
+Monolog on GitHub and fixed the issue in a branch named `bugfix`. Now you want
+to install that version of monolog in your local project.
+
+You are using `symfony/monolog-bundle` which requires `monolog/monolog` version
+`1.*`. So you need your `dev-bugfix` to match that constraint.
+
+Just add this to your project's root `composer.json`:
+
+    {
+        "repositories": [
+            {
+                "type": "vcs",
+                "url": "https://github.com/you/monolog"
+            }
+        ],
+        "require": {
+            "symfony/monolog-bundle": "2.0",
+            "monolog/monolog": "dev-bugfix as 1.0.x-dev"
+        }
+    }
+
+That will fetch the `dev-bugfix` version of `monolog/monolog` from your GitHub
+and alias it to `1.0.x-dev`.
+
+> **Note:** If a package with inline aliases is required, the alias (right of
+> the `as`) is used as the version constraint. The part left of the `as` is
+> discarded. As a consequence, if A requires B and B requires `monolog/monolog`
+> version `dev-bugfix as 1.0.x-dev`, installing A will make B require
+> `1.0.x-dev`, which may exist as a branch alias or an actual `1.0` branch. If
+> it does not, it must be re-inline-aliased in A's `composer.json`.
+
+> **Note:** Inline aliasing should be avoided, especially for published
+> packages. If you found a bug, try and get your fix merged upstream. This
+> helps to avoid issues for users of your package.