More usage docs

Author: pinkeen

README.md

@@ -16,7 +16,11 @@ It's (kind-of) an alternative to two other great plugins (differences will becom
  * [cweagans/composer-patches](https://github.com/cweagans/composer-patches)
 
 
-**If you're already convinced skip to [Usage Documentation](docs/usage.md).**
+**Continue reading this document for general description or skip to:**
+
+ * [Usage Documentation](docs/usage.md)
+ * [Creating Patches Howto](docs/creating-patches.md)
+ * [Testing](docs/testing.md)
 
 ## Feature comparison table
 
@@ -86,13 +90,4 @@ plugins have done their work so patching source files in vendor will have no eff
  purpose. I can hardly imagine a legit use case when it would be desirable that installing package X will automatically 
  patch some other package Y in your project without explicitly being advertised as a patchset.
 
-## Running tests
-
-Just start `vendor/bin/phpunit`.
-If you want to see the output of commands executed during functional testing use the `--debug` switch:
-```
-vendor/bin/phpunit --debug
-```
 
-It's nice to also add the `--testdox` switch then.
-   

docs/creating-patches.md

@@ -0,0 +1,21 @@
+# Testing the plugin
+
+## Composer sandbox
+
+This plugin uses a special sandbox which allows it to run composer as a separate process during testing.
+
+A fake local packagist repository is created from [package definitions](tests/Functional/Fixtures/Packages) 
+for the purpose of testing by using internally [Satis](https://github.com/composer/satis) as a library.
+
+See the [ComposerSandbox](tests/Functional/Fixtures/ComposerSandbox.php) class for the details.
+
+## Running tests
+
+Just start `vendor/bin/phpunit`.
+If you want to see the output of commands executed during functional testing use the `--debug` switch:
+```
+vendor/bin/phpunit --debug
+```
+
+It's nice to also add the `--testdox` switch then.
+   

docs/testing.md

@@ -1,21 +1,99 @@
-## Usage
+# Basic Usage
 
-### Create *patchset* composer package
+There are two ways to specify and store patches, you can use any of them or both.
 
-### Define patches in your root package
+## Create *patchset* composer package
 
-### Applying patches to root package (root project folder)
+_Use this way to easily distribute your patchset and use it in multiple projects_
+
+ 1. Create a new composer package and change the package type in `composer.json` to `patchset` 
+   so it looks like this:
+   
+   ```json
+    {
+        "name": "your-vendor/your-patchset-name",
+        "type": "patchset",
+        "version": "1.0",
+        "require": {
+            "creativestyle/composer-plugin-patchset": "^1.0"
+        }
+    } 
+   ```
+   
+ 2. Place your diff patch files in any directories inside the package you want
+ 3. Define the patches in `composer.json` like this:
+   
+   ```json
+    {
+        "name": "your-vendor/your-patchset-name",
+        "type": "patchset",
+        "version": "1.0",
+        "require": {
+            "creativestyle/composer-plugin-patchset": "^1.0"
+        },
+        "extra": {
+            "patchset": {
+                "some-vendor-a/package-to-patch": [
+                    {
+                        "description": "Short patch description that is mandatory",
+                        "filename": "path/to/the-patch-file-relative-to-patchset-root.diff"
+                    },
+                    {
+                        "description": "Patches with no version specified will be always applied",
+                        "filename": "second-patch-for-the-same-package.diff"
+                    }
+                ],
+                "some-vendor-b/package-to-patch": [
+                    {
+                        "description": "Patch some other package",
+                        "filename": "patches/your-other-package-patch.diff",
+                    }
+                ]
+            }
+        }
+    }
+   ```   
+
+## Define patches in your root package
+
+# Composer json configuration reference 
+
+## Patch properties
+
+### `description` (string, mandatory)
+
+Short description (or name) of your patch. Keep it short as it will be displayed during patching.
+
+### `filename` (string, mandatory)
+
+Path to your diff file relative to the root of your patchset. Patches can be stored anywhere within
+the package.
+
+### `version-constraint` (string, default: `"*"`)
+
+A composer semver version constraint. If specified then the patch application will be attempted 
+only if the target package's version matches the constraint.
+
+See [composer documenation](https://getcomposer.org/doc/articles/versions.md) for exact syntax reference.
+
+### `strip-path-components` (integer, default: `1`)
+
+How many leading path components to strip from filenames in diff when applying the patch.
+
+This has the same effect as the `-p{x}` switch of the patch command, where `{x}` is the value of this parameter.
+
+For 99% of the patches this will be the default `1`. Set this only if your patch was generated in some non-standard way.
+
+# Notable use-cases
+
+## Applying patches to root package (root project folder)
 
 Define patches as you normally would. If your root package is not named the you should use special
 `__root__` as package name.
 
-**CAUTION** Since root package cannot be reinstalled once patches are applied they cannot be removed!
+**CAUTION!** Since root package cannot be reinstalled once patches are applied they cannot be removed!
 This means that if you want to remove patches applied to root package you should reinstall the whole
 project manually. The plugin will warn you when this is the case but will not fail. It will try
 to apply any new root package patches though.
 
 __New patches will be applied to the root package but then _application order_ is not guaranteed.__
-
-### Options
-
-#### Strip defined number of components when applying patch (`-pX`)