Enhance plugin-descriptor.properties guide

* extract doc from the descriptor
* make obvious that plugin authors will have to release a new version for each elasticsearch version

dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties

@@ -24,7 +24,7 @@
 # jvm=true
 # classname=foo.bar.BazPlugin
 # description=My cool plugin
-# version=2.0
+# version=2.0.0-rc1
 # elasticsearch.version=2.0
 # java.version=1.7
 #
@@ -64,6 +64,10 @@ classname=${elasticsearch.plugin.classname}
 java.version=${maven.compiler.target}
 #
 # 'elasticsearch.version' version of elasticsearch compiled against
+# You will have to release a new version of the plugin for each new
+# elasticsearch release. This version is checked when the plugin
+# is loaded so Elasticsearch will refuse to start in the presence of
+# plugins with the incorrect elasticsearch.version.
 elasticsearch.version=${elasticsearch.version}
 #
 ### deprecated elements for jvm plugins :

docs/plugins/authors.asciidoc

@@ -42,6 +42,72 @@ can fill in the necessary values in the `pom.xml` for your plugin. For
 instance, see
 https://github.com/elastic/elasticsearch/blob/master/plugins/site-example/pom.xml[`plugins/site-example/pom.xml`].
 
+[float]
+==== Mandatory elements for all plugins
+
+
+[cols="<,<,<",options="header",]
+|=======================================================================
+|Element                    | Type   | Description
+
+|`description`              |String  | simple summary of the plugin
+
+|`version`                  |String  | plugin's version
+
+|`name`                     |String  | the plugin name
+
+|=======================================================================
+
+
+
+[float]
+==== Mandatory elements for Java plugins
+
+
+[cols="<,<,<",options="header",]
+|=======================================================================
+|Element                    | Type   | Description
+
+|`jvm`                      |Boolean | true if the `classname` class should be loaded
+from jar files in the root directory of the plugin.
+Note that only jar files in the root directory are added to the classpath for the plugin!
+If you need other resources, package them into a resources jar.
+
+|`classname`                |String  | the name of the class to load, fully-qualified.
+
+|`java.version`             |String  | version of java the code is built against.
+Use the system property `java.specification.version`. Version string must be a sequence
+of nonnegative decimal integers separated by "."'s and may have leading zeros.
+
+|`elasticsearch.version`    |String  | version of elasticsearch compiled against.
+
+|=======================================================================
+
+[IMPORTANT]
+.Plugin release lifecycle
+==============================================
+
+You will have to release a new version of the plugin for each new elasticsearch release.
+This version is checked when the plugin is loaded so Elasticsearch will refuse to start
+in the presence of plugins with the incorrect `elasticsearch.version`.
+
+==============================================
+
+
+[float]
+==== Mandatory elements for Site plugins
+
+
+[cols="<,<,<",options="header",]
+|=======================================================================
+|Element                    | Type   | Description
+
+|`site`                     |Boolean | true to indicate contents of the `_site/`
+directory in the root of the plugin should be served.
+
+|=======================================================================
+
+
 [float]
 === Testing your plugin