Add basic docs

LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2006-2017, SilverStripe Limited - www.silverstripe.com
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of SilverStripe nor the names of its contributors may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.

README.md

@@ -0,0 +1,108 @@
+# SilverStripe recipe-plugin
+
+## Introduction
+
+This plugin enhances composer and allows for the installation of "silverstripe-recipe" packages.
+These recipes allow for the following features:
+
+ - The ability to provide project resource files. These are copied to the appropriate project root location
+   on install, and can be safely modified by the developer. On subsequent updates to a later recipe,
+   composer will inform the user if a project file has been updated, and will ensure new files are
+   copied as they are introduced to the recipe.
+ - Recipes are composable, so resources or dependencies that are required by multiple recipes can include one another,
+   rather than having to duplicate content.
+ - Recipes also can be used as a base composer project.
+ - A `require-recipe` command to inline a recipe into the root composer.json, allowing the developer to customise the
+   recipe dependencies without mandating the inclusion of all requirements directly.
+ - An `upgrade-recipe` command to upgrade to a newer version of a recipe.
+
+## Example output
+
+![example-output](docs/_images/require-usage.png)
+
+## Creating a new project
+
+Recipes can be introduced to any existing project (even if not created on a silverstripe base project)
+
+
+    :::
+    $ composer init
+    $ composer require silverstripe/recipe-plugin ^0.1
+    $ composer require-recipe silverstripe/recipe-cms ^4.0@dev
+
+
+Alternatively, instead of having to install the recipe-plugin manually, you can require the recipe
+directly and inline this as a subsequent command. This is necessary to make the new commands available
+to the command line.
+
+
+    :::
+    $ composer init
+    $ composer require silverstripe/recipe-cms ^4.0@dev
+    $ composer upgrade-recipe silverstripe/recipe-cms
+
+
+Alternatively you can create a new project based on an existing recipe
+
+
+    :::
+    $ composer create-project silverstripe/recipe-cms ./myssproject ^4.0@dev
+
+
+## Upgrading recipes
+
+Any existing recipe, whether installed via `composer require` or `composer require-recipe` can be safely upgraded
+via `composer upgrade-recipe`.
+
+When upgrading a version constraint is recommended, but not necessary. If omitted, then the existing installed
+version will be detected, and a safe default chosen.
+
+
+    :::
+    $ composer upgrade-recipe silverstripe/recipe-cms ^1.0@dev
+
+
+## Installing or upgrading recipes without inlining them
+
+If desired, the optional inline behaviour of recipes can be omitted. Simply use the composer commands `require` and
+`update` in place of `require-recipe` and `update-recipe` respectively. This will not disable the project files
+feature, but will not inline the recipe directly, keeping your root composer.json from getting cluttered.
+
+If you have already inlined a recipe, it will be necessary to manually remove any undesired inlined requirements
+manually, and the recipe will need to be included with `require` subsequently.
+
+Note that using this method it's not necessary to include the `silverstripe/recipe-plugin` in the root project
+for this to work.
+
+## Building a recipe
+
+Recipe types should follow the following rules:
+
+ - No mandatory resources excluding project files
+ - Should require any `autoload` of the following composer settings, as these are discarded on inline.
+   Likewise any `dev` options, as these are ignored outside of the root project. The exception to this
+   is when these values are useful as a base project only.
+ - Library type must be 'silverstripe-recipe'
+ - Library must have `silverstripe/recipe-plugin` as a dependency.
+
+An example recipe:
+
+    :::json
+    {
+        "name": "silverstripe/example-recipe,
+        "description": "Example silverstripe recipe",
+        "type": "silverstripe-recipe",
+        "require": {
+            "silverstripe/recipe-plugin": "^0.1",
+            "silverstripe/recipe-cms": "^4.0",
+            "silverstripe/blog": "^3.0@dev",
+            "silverstripe/lumberjack": "^2.1@dev",
+        },
+        "extra": {
+            "project-files": [
+                "mysite/_config/blogsettings.yml"
+            ]
+        },
+        "prefer-stable": true,
+        "minimum-stability": "dev"
+    }