From 81f33e9739abd03ece2f57f6d54c1624226f552c Mon Sep 17 00:00:00 2001
From: Bilal Amarni <bamarni@users.noreply.github.com>
Date: Mon, 2 May 2016 09:19:40 +0200
Subject: [PATCH 1/3] document plugin capabilities (closes #5262)

---
 doc/articles/plugins.md | 72 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/doc/articles/plugins.md b/doc/articles/plugins.md
index b4997d22d..9af6103c7 100644
--- a/doc/articles/plugins.md
+++ b/doc/articles/plugins.md
@@ -183,6 +183,76 @@ class AwsPlugin implements PluginInterface, EventSubscriberInterface
 }
 ```
 
+
+## Plugin capabilities
+
+Composer defines a standard set of capabilities which may be implemented by plugins
+through the [`Composer\Plugin\Capable`][8] interface.
+
+### Command provider
+
+The [`Composer\Plugin\Capability\CommandProvider`][9] capability allows to register
+additional commands for Composer :
+
+```php
+<?php
+
+namespace My\Composer;
+
+use Composer\Plugin\Capability\CommandProvider as CommandProviderCapability;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Composer\Command\BaseCommand;
+
+class CommandProvider implements CommandProviderCapability
+{
+    public function getCommands()
+    {
+        return array(new Command);
+    }
+}
+
+class Command extends BaseCommand
+{
+    protected function configure()
+    {
+        $this->setName('custom-plugin-command');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        $output->writeln('Executing');
+    }
+}
+```
+
+Once the plugin exposes this capability, `custom-plugin-command` is
+available alongside Composer commands :
+
+```php
+<?php
+
+namespace My\Composer;
+
+use Composer\Composer;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+
+class Plugin implements PluginInterface
+{
+    public function activate(Composer $composer, IOInterface $io)
+    {
+    }
+
+    public function getCapabilities()
+    {
+        return array(
+            'Composer\Plugin\Capability\CommandProvider' => 'My\Composer\CommandProvider',
+        );
+    }
+}
+```
+
 ## Using Plugins
 
 Plugin packages are automatically loaded as soon as they are installed and will
@@ -202,3 +272,5 @@ local project plugins are loaded.
 [5]: https://github.com/composer/composer/blob/master/src/Composer/IO/IOInterface.php
 [6]: https://github.com/composer/composer/blob/master/src/Composer/EventDispatcher/EventSubscriberInterface.php
 [7]: ../01-basic-usage.md#package-versions
+[8]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capable.php
+[9]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capability/CommandProvider.php

From c1bc50dd2acca9351803abd5fbf1af86b1874dfd Mon Sep 17 00:00:00 2001
From: Bilal Amarni <bamarni@users.noreply.github.com>
Date: Mon, 2 May 2016 12:50:25 +0200
Subject: [PATCH 2/3] add missing interface

---
 doc/articles/plugins.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/articles/plugins.md b/doc/articles/plugins.md
index 9af6103c7..e7ecf97e2 100644
--- a/doc/articles/plugins.md
+++ b/doc/articles/plugins.md
@@ -237,8 +237,9 @@ namespace My\Composer;
 use Composer\Composer;
 use Composer\IO\IOInterface;
 use Composer\Plugin\PluginInterface;
+use Composer\Plugin\Capable;
 
-class Plugin implements PluginInterface
+class Plugin implements PluginInterface, Capable
 {
     public function activate(Composer $composer, IOInterface $io)
     {

From 253a30793d4a77354f5259f424adbcd87c757d88 Mon Sep 17 00:00:00 2001
From: Bilal Amarni <bamarni@users.noreply.github.com>
Date: Tue, 3 May 2016 08:22:54 +0200
Subject: [PATCH 3/3] updates

---
 doc/articles/plugins.md | 66 +++++++++++++++++++++++------------------
 1 file changed, 37 insertions(+), 29 deletions(-)

diff --git a/doc/articles/plugins.md b/doc/articles/plugins.md
index e7ecf97e2..bf72aa235 100644
--- a/doc/articles/plugins.md
+++ b/doc/articles/plugins.md
@@ -183,11 +183,42 @@ class AwsPlugin implements PluginInterface, EventSubscriberInterface
 }
 ```
 
-
 ## Plugin capabilities
 
-Composer defines a standard set of capabilities which may be implemented by plugins
-through the [`Composer\Plugin\Capable`][8] interface.
+Composer defines a standard set of capabilities which may be implemented by plugins.
+Their goal is to make the plugin ecosystem more stable as it reduces the need to mess
+with [`Composer\Composer`][4]'s internal state, by providing explicit extension points
+for common plugin requirements.
+
+Capable Plugins classes must implement the [`Composer\Plugin\Capable`][8] interface
+and declare their capabilities in the `getCapabilities()` method. 
+This method must return an array, with the _key_ as a Composer Capability class name, 
+and the _value_ as the Plugin's own implementation class name of said Capability:
+
+```php
+<?php
+
+namespace My\Composer;
+
+use Composer\Composer;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+use Composer\Plugin\Capable;
+
+class Plugin implements PluginInterface, Capable
+{
+    public function activate(Composer $composer, IOInterface $io)
+    {
+    }
+
+    public function getCapabilities()
+    {
+        return array(
+            'Composer\Plugin\Capability\CommandProvider' => 'My\Composer\CommandProvider',
+        );
+    }
+}
+```
 
 ### Command provider
 
@@ -226,33 +257,9 @@ class Command extends BaseCommand
 }
 ```
 
-Once the plugin exposes this capability, `custom-plugin-command` is
-available alongside Composer commands :
+Now the `custom-plugin-command` is available alongside Composer commands.
 
-```php
-<?php
-
-namespace My\Composer;
-
-use Composer\Composer;
-use Composer\IO\IOInterface;
-use Composer\Plugin\PluginInterface;
-use Composer\Plugin\Capable;
-
-class Plugin implements PluginInterface, Capable
-{
-    public function activate(Composer $composer, IOInterface $io)
-    {
-    }
-
-    public function getCapabilities()
-    {
-        return array(
-            'Composer\Plugin\Capability\CommandProvider' => 'My\Composer\CommandProvider',
-        );
-    }
-}
-```
+> _Composer commands are based on the [Symfony Console Component][10]._
 
 ## Using Plugins
 
@@ -275,3 +282,4 @@ local project plugins are loaded.
 [7]: ../01-basic-usage.md#package-versions
 [8]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capable.php
 [9]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capability/CommandProvider.php
+[10]: http://symfony.com/doc/current/components/console/introduction.html