diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ed50f47 --- /dev/null +++ b/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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..baad264 --- /dev/null +++ b/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" + } \ No newline at end of file diff --git a/docs/_images/require-usage.png b/docs/_images/require-usage.png new file mode 100644 index 0000000..57b2e23 Binary files /dev/null and b/docs/_images/require-usage.png differ diff --git a/docs/_images/require-usage@2.png b/docs/_images/require-usage@2.png new file mode 100644 index 0000000..1c83df4 Binary files /dev/null and b/docs/_images/require-usage@2.png differ