diff --git a/doc/fixtures/fixtures.md b/doc/fixtures/fixtures.md
new file mode 100644
index 000000000..fd77f3c37
--- /dev/null
+++ b/doc/fixtures/fixtures.md
@@ -0,0 +1,20 @@
+`Composer` type repository fixtures
+=======================
+
+This directory contains some examples of what `composer` type repositories can look like. They serve as illustrating examples accompanying the docs, but can also be used as (initial) fixtures for tests.
+
+* `repo-composer-plain` is a simple, plain `packages.json` file
+* `repo-composer-with-includes` uses the `includes` mechanism
+* `repo-composer-with-providers` uses the `providers` mechanism
+
+Sample Packages used in these fixtures
+-------
+
+All these repositories contain the following packages.
+
+* `foo/bar` versions 1.0.0, 1.0.1 and 1.1.0; dev-default and 1.0.x-dev branches. On dev-default and in 1.1.0, `bar/baz` ~1.0 is required.
+* `qux/quux` only has a dev-default branch. It `replace`s `gar/nix`.
+* `gar/nix` has a 1.0.0 version and a dev-default branch. It is being replaced by `qux/quux`.
+* `bar/baz` has a 1.0.0 version and 1.0.x-dev as well as dev-default branches. Additionally, 1.1.x-dev is a branch alias for dev-default.
+
+
diff --git a/doc/fixtures/repo-composer-plain/packages.json b/doc/fixtures/repo-composer-plain/packages.json
new file mode 100644
index 000000000..219051998
--- /dev/null
+++ b/doc/fixtures/repo-composer-plain/packages.json
@@ -0,0 +1,158 @@
+{
+    "packages": {
+        "bar/baz": {
+            "1.0.0": {
+                "name": "bar/baz",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "35810817c14d"
+                },
+                "time": "2014-10-13 12:04:55",
+                "type": "library"
+            },
+            "1.0.x-dev": {
+                "name": "bar/baz",
+                "version": "1.0.x-dev",
+                "version_normalized": "1.0.9999999.9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "ffff9aae6ed5"
+                },
+                "time": "2014-10-13 12:05:37",
+                "type": "library"
+            },
+            "dev-default": {
+                "name": "bar/baz",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "f317e556f2e2"
+                },
+                "time": "2014-10-13 12:06:45",
+                "type": "library",
+                "extra": {
+                    "branch-alias": {
+                        "dev-default": "1.1.x-dev"
+                    }
+                }
+            }
+        },
+        "foo/bar": {
+            "1.0.0": {
+                "name": "foo/bar",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "249dec95a52a"
+                },
+                "time": "2014-10-11 15:42:00",
+                "type": "library"
+            },
+            "1.0.1": {
+                "name": "foo/bar",
+                "version": "1.0.1",
+                "version_normalized": "1.0.1.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "21e3328295d4"
+                },
+                "time": "2014-10-11 15:45:56",
+                "type": "library"
+            },
+            "1.0.x-dev": {
+                "name": "foo/bar",
+                "version": "1.0.x-dev",
+                "version_normalized": "1.0.9999999.9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "14dc17c8e860"
+                },
+                "time": "2014-10-11 15:45:59",
+                "type": "library"
+            },
+            "1.1.0": {
+                "name": "foo/bar",
+                "version": "1.1.0",
+                "version_normalized": "1.1.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "d2fa3e69ad5b"
+                },
+                "require": {
+                    "bar/baz": "~1.0"
+                },
+                "time": "2014-10-11 15:43:16",
+                "type": "library"
+            },
+            "dev-default": {
+                "name": "foo/bar",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "8e5a5c224336"
+                },
+                "require": {
+                    "bar/baz": "~1.0"
+                },
+                "time": "2014-10-11 15:43:18",
+                "type": "library"
+            }
+        },
+        "gar/nix": {
+            "1.0.0": {
+                "name": "gar/nix",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "44977145d64e"
+                },
+                "time": "2014-10-13 12:03:33",
+                "type": "library"
+            },
+            "dev-default": {
+                "name": "gar/nix",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "51cca95a31c2"
+                },
+                "time": "2014-10-13 12:03:35",
+                "type": "library"
+            }
+        },
+        "qux/quux": {
+            "dev-default": {
+                "name": "qux/quux",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "4a10a567baa5"
+                },
+                "replace": {
+                    "gar/nix": "1.0.*"
+                },
+                "time": "2014-10-11 15:48:15",
+                "type": "library"
+            }
+        }
+    }
+}
diff --git a/doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json b/doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json
new file mode 100644
index 000000000..219051998
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-includes/include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json
@@ -0,0 +1,158 @@
+{
+    "packages": {
+        "bar/baz": {
+            "1.0.0": {
+                "name": "bar/baz",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "35810817c14d"
+                },
+                "time": "2014-10-13 12:04:55",
+                "type": "library"
+            },
+            "1.0.x-dev": {
+                "name": "bar/baz",
+                "version": "1.0.x-dev",
+                "version_normalized": "1.0.9999999.9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "ffff9aae6ed5"
+                },
+                "time": "2014-10-13 12:05:37",
+                "type": "library"
+            },
+            "dev-default": {
+                "name": "bar/baz",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "f317e556f2e2"
+                },
+                "time": "2014-10-13 12:06:45",
+                "type": "library",
+                "extra": {
+                    "branch-alias": {
+                        "dev-default": "1.1.x-dev"
+                    }
+                }
+            }
+        },
+        "foo/bar": {
+            "1.0.0": {
+                "name": "foo/bar",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "249dec95a52a"
+                },
+                "time": "2014-10-11 15:42:00",
+                "type": "library"
+            },
+            "1.0.1": {
+                "name": "foo/bar",
+                "version": "1.0.1",
+                "version_normalized": "1.0.1.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "21e3328295d4"
+                },
+                "time": "2014-10-11 15:45:56",
+                "type": "library"
+            },
+            "1.0.x-dev": {
+                "name": "foo/bar",
+                "version": "1.0.x-dev",
+                "version_normalized": "1.0.9999999.9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "14dc17c8e860"
+                },
+                "time": "2014-10-11 15:45:59",
+                "type": "library"
+            },
+            "1.1.0": {
+                "name": "foo/bar",
+                "version": "1.1.0",
+                "version_normalized": "1.1.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "d2fa3e69ad5b"
+                },
+                "require": {
+                    "bar/baz": "~1.0"
+                },
+                "time": "2014-10-11 15:43:16",
+                "type": "library"
+            },
+            "dev-default": {
+                "name": "foo/bar",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "8e5a5c224336"
+                },
+                "require": {
+                    "bar/baz": "~1.0"
+                },
+                "time": "2014-10-11 15:43:18",
+                "type": "library"
+            }
+        },
+        "gar/nix": {
+            "1.0.0": {
+                "name": "gar/nix",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "44977145d64e"
+                },
+                "time": "2014-10-13 12:03:33",
+                "type": "library"
+            },
+            "dev-default": {
+                "name": "gar/nix",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "51cca95a31c2"
+                },
+                "time": "2014-10-13 12:03:35",
+                "type": "library"
+            }
+        },
+        "qux/quux": {
+            "dev-default": {
+                "name": "qux/quux",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http://some.where/over/the/rainbow/",
+                    "reference": "4a10a567baa5"
+                },
+                "replace": {
+                    "gar/nix": "1.0.*"
+                },
+                "time": "2014-10-11 15:48:15",
+                "type": "library"
+            }
+        }
+    }
+}
diff --git a/doc/fixtures/repo-composer-with-includes/packages.json b/doc/fixtures/repo-composer-with-includes/packages.json
new file mode 100644
index 000000000..1ef97530a
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-includes/packages.json
@@ -0,0 +1,10 @@
+{
+    "packages": [
+
+    ],
+    "includes": {
+        "include/all$5fa86b937f0502d92f776072cd49c002dca742b9.json": {
+            "sha1": "5fa86b937f0502d92f776072cd49c002dca742b9"
+        }
+    }
+}
diff --git a/doc/fixtures/repo-composer-with-providers/p/bar/baz$923363b3c22e73abb2e3fd891c8156dd4d0821a97fd3e428bc910833e3e46dbe.json b/doc/fixtures/repo-composer-with-providers/p/bar/baz$923363b3c22e73abb2e3fd891c8156dd4d0821a97fd3e428bc910833e3e46dbe.json
new file mode 100644
index 000000000..94a43b019
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-providers/p/bar/baz$923363b3c22e73abb2e3fd891c8156dd4d0821a97fd3e428bc910833e3e46dbe.json
@@ -0,0 +1,50 @@
+{
+    "packages": {
+        "bar\/baz": {
+            "1.0.0": {
+                "name": "bar\/baz",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "35810817c14d"
+                },
+                "time": "2014-10-13 12:04:55",
+                "type": "library",
+                "uid": 0
+            },
+            "1.0.x-dev": {
+                "name": "bar\/baz",
+                "version": "1.0.x-dev",
+                "version_normalized": "1.0.9999999.9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "ffff9aae6ed5"
+                },
+                "time": "2014-10-13 12:05:37",
+                "type": "library",
+                "uid": 1
+            },
+            "dev-default": {
+                "name": "bar\/baz",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "f317e556f2e2"
+                },
+                "time": "2014-10-13 12:06:45",
+                "type": "library",
+                "extra": {
+                    "branch-alias": {
+                        "dev-default": "1.1.x-dev"
+                    }
+                },
+                "uid": 2
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/doc/fixtures/repo-composer-with-providers/p/foo/bar$4baabb3303afa3e34a4d3af18fb138e5f3b79029c1f8d9ab5b477ea15776ba0a.json b/doc/fixtures/repo-composer-with-providers/p/foo/bar$4baabb3303afa3e34a4d3af18fb138e5f3b79029c1f8d9ab5b477ea15776ba0a.json
new file mode 100644
index 000000000..7dc7cc91e
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-providers/p/foo/bar$4baabb3303afa3e34a4d3af18fb138e5f3b79029c1f8d9ab5b477ea15776ba0a.json
@@ -0,0 +1,77 @@
+{
+    "packages": {
+        "foo\/bar": {
+            "1.0.0": {
+                "name": "foo\/bar",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "249dec95a52a"
+                },
+                "time": "2014-10-11 15:42:00",
+                "type": "library",
+                "uid": 3
+            },
+            "1.0.1": {
+                "name": "foo\/bar",
+                "version": "1.0.1",
+                "version_normalized": "1.0.1.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "21e3328295d4"
+                },
+                "time": "2014-10-11 15:45:56",
+                "type": "library",
+                "uid": 4
+            },
+            "1.0.x-dev": {
+                "name": "foo\/bar",
+                "version": "1.0.x-dev",
+                "version_normalized": "1.0.9999999.9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "14dc17c8e860"
+                },
+                "time": "2014-10-11 15:45:59",
+                "type": "library",
+                "uid": 5
+            },
+            "1.1.0": {
+                "name": "foo\/bar",
+                "version": "1.1.0",
+                "version_normalized": "1.1.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "d2fa3e69ad5b"
+                },
+                "require": {
+                    "bar\/baz": "~1.0"
+                },
+                "time": "2014-10-11 15:43:16",
+                "type": "library",
+                "uid": 6
+            },
+            "dev-default": {
+                "name": "foo\/bar",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "8e5a5c224336"
+                },
+                "require": {
+                    "bar\/baz": "~1.0"
+                },
+                "time": "2014-10-11 15:43:18",
+                "type": "library",
+                "uid": 7
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/doc/fixtures/repo-composer-with-providers/p/gar/nix$5d210670cb46c8364c8e3fb449967b9bea558b971e5b082f330ae4f1d484c321.json b/doc/fixtures/repo-composer-with-providers/p/gar/nix$5d210670cb46c8364c8e3fb449967b9bea558b971e5b082f330ae4f1d484c321.json
new file mode 100644
index 000000000..512b8d882
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-providers/p/gar/nix$5d210670cb46c8364c8e3fb449967b9bea558b971e5b082f330ae4f1d484c321.json
@@ -0,0 +1,50 @@
+{
+    "packages": {
+        "qux\/quux": {
+            "dev-default": {
+                "name": "qux\/quux",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "4a10a567baa5"
+                },
+                "replace": {
+                    "gar\/nix": "1.0.*"
+                },
+                "time": "2014-10-11 15:48:15",
+                "type": "library",
+                "uid": 10
+            }
+        },
+        "gar\/nix": {
+            "1.0.0": {
+                "name": "gar\/nix",
+                "version": "1.0.0",
+                "version_normalized": "1.0.0.0",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "44977145d64e"
+                },
+                "time": "2014-10-13 12:03:33",
+                "type": "library",
+                "uid": 8
+            },
+            "dev-default": {
+                "name": "gar\/nix",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "51cca95a31c2"
+                },
+                "time": "2014-10-13 12:03:35",
+                "type": "library",
+                "uid": 9
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/doc/fixtures/repo-composer-with-providers/p/provider-active$1893a061e579543822389ecd12d791c612db0c05e22d90e9286e233cacd86ed8.json b/doc/fixtures/repo-composer-with-providers/p/provider-active$1893a061e579543822389ecd12d791c612db0c05e22d90e9286e233cacd86ed8.json
new file mode 100644
index 000000000..b82eb418e
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-providers/p/provider-active$1893a061e579543822389ecd12d791c612db0c05e22d90e9286e233cacd86ed8.json
@@ -0,0 +1,16 @@
+{
+    "providers": {
+        "bar\/baz": {
+            "sha256": "923363b3c22e73abb2e3fd891c8156dd4d0821a97fd3e428bc910833e3e46dbe"
+        },
+        "foo\/bar": {
+            "sha256": "4baabb3303afa3e34a4d3af18fb138e5f3b79029c1f8d9ab5b477ea15776ba0a"
+        },
+        "gar\/nix": {
+            "sha256": "5d210670cb46c8364c8e3fb449967b9bea558b971e5b082f330ae4f1d484c321"
+        },
+        "qux\/quux": {
+            "sha256": "c142d1a07ca354be46b613f59f1d601923a5a00ccc5fcce50a77ecdd461eb72d"
+        }
+    }
+}
\ No newline at end of file
diff --git a/doc/fixtures/repo-composer-with-providers/p/qux/quux$c142d1a07ca354be46b613f59f1d601923a5a00ccc5fcce50a77ecdd461eb72d.json b/doc/fixtures/repo-composer-with-providers/p/qux/quux$c142d1a07ca354be46b613f59f1d601923a5a00ccc5fcce50a77ecdd461eb72d.json
new file mode 100644
index 000000000..014187206
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-providers/p/qux/quux$c142d1a07ca354be46b613f59f1d601923a5a00ccc5fcce50a77ecdd461eb72d.json
@@ -0,0 +1,22 @@
+{
+    "packages": {
+        "qux\/quux": {
+            "dev-default": {
+                "name": "qux\/quux",
+                "version": "dev-default",
+                "version_normalized": "9999999-dev",
+                "source": {
+                    "type": "hg",
+                    "url": "http:\/\/some.where\/over\/the\/rainbow\/",
+                    "reference": "4a10a567baa5"
+                },
+                "replace": {
+                    "gar\/nix": "1.0.*"
+                },
+                "time": "2014-10-11 15:48:15",
+                "type": "library",
+                "uid": 10
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/doc/fixtures/repo-composer-with-providers/packages.json b/doc/fixtures/repo-composer-with-providers/packages.json
new file mode 100644
index 000000000..65968a861
--- /dev/null
+++ b/doc/fixtures/repo-composer-with-providers/packages.json
@@ -0,0 +1,9 @@
+{
+    "packages": [],
+    "providers-url": "\/p\/%package%$%hash%.json",
+    "provider-includes": {
+        "p\/provider-active$1893a061e579543822389ecd12d791c612db0c05e22d90e9286e233cacd86ed8.json": {
+            "sha256": "1893a061e579543822389ecd12d791c612db0c05e22d90e9286e233cacd86ed8"
+        }
+    }
+}
\ No newline at end of file