Merge "Added new chapter Plugin Versioning System"

plugindocs/fuel-plugin-sdk-guide/create-plugin.rst

@@ -23,4 +23,5 @@ This section includes the following topics:
    create-plugin/plugin-node-roles.rst
    create-plugin/modify-ui.rst
    create-plugin/plugin-repos.rst
-   create-plugin/add-driverlog.rst
+   create-plugin/add-driverlog.rst
+   create-plugin/plugin-versioning-system.rst

plugindocs/fuel-plugin-sdk-guide/create-plugin/describe-plugin.rst

@@ -38,8 +38,7 @@ The Fuel Plugin Builder generates three files:
      The allowed name characters are lowercase letters, dash ``-``, and
      underscore ``_``.
    * ``title`` -- Human-readable plugin name displayed on the Fuel web UI.
-   * ``version`` -- Plugin version. For guidelines, see
-     `Semantic Versioning 2.0.0 <http://semver.org/>`_.
+   * ``version`` -- Plugin version. For guidelines, see :ref:`plugin_versioning_system`.
    * ``licenses`` -- List the licenses under which your plugin can be
      distributed.
    * ``authors`` -- Name of the plugin author. A company or an individual.
@@ -97,6 +96,11 @@ The Fuel Plugin Builder generates three files:
      format version introduces new features and, possibly, deprecates some of
      the old ones. The Fuel master node must support the specific
      ``package_version``, otherwise, you cannot install the plugin.
+   * ``build_version`` -- A version of the build that allows to iterate the
+     package version without updating the plugin version. You can specify
+     a value in any format, such as timestamp and so on. If the value is empty,
+     fpb adds "1" at the end of the plugin's output file name. For example,
+     ``plugin-x.x-x.x.x-1.rpm``.
 
    See the `metadata.yaml example <https://github.com/openstack/fuel-plugin-openbook/blob/master/metadata.yaml>`_.
 

plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-versioning-system.rst

@@ -0,0 +1,62 @@
+
+.. _plugin_versioning_system:
+
+Plugin versioning system
+------------------------
+
+When the developer adds new functionality to a plugin, minor updates
+or security fixes should be delivered.
+The plugin developer creates a new version of the plugin: this can be
+a major version or a minor one:
+
+* Major -- Changes in API, functionality, major OpenStack release introduced.
+* Minor -- Security fixes only.
+
+The plugin versioning is the following:
+
++-----+-----------------------+---------------------+-----------------+---------+---------+
+|     | **Plugin file format**|**fuel-plugin value**|**metadata.yaml**|**major**|**minor**|
++-----+-----------------------+---------------------+-----------------+---------+---------+
+| RPM | fuel-plugin-1.0-1.0.0 | 1.0                 | 1.0.1           |1.0.0    | 1.0.1   |
++-----+-----------------------+---------------------+-----------------+---------+---------+
+
+**Plugin versioning example**
+
+If a plugin has version ``1.0.1`` in the ``metadat.yaml`` file, the file name
+of the plugin must be ``plugin-1.0-1.0.1-N.rpm``.
+
+If you use the default setting of the Fuel plugin builder, N equals 1. You can
+also specify a value from the ``build_version`` variable defined in the
+:ref:`metadata.yaml` file that allows to iterate the package version without
+updating the plugin version.
+
+Update procedure
+~~~~~~~~~~~~~~~~
+
++-----+----------+-------------------------------------------------------------------------------------+
+|     |**Update**|**Limitations**                                                                      |
++-----+----------+-------------------------------------------------------------------------------------+
+| fp  |  No      | 1.0                                                                                 | 
++-----+----------+-------------------------------------------------------------------------------------+
+| RPM |  Yes     | Can be updated to minor version only with *fuel plugins --update <fuel-plugin-file>*|
+|     |          | command. To get a major one, user has to download it from `Fuel Plugins Catalog     |
+|     |          | <https://www.mirantis.com/validated-solution-integrations/fuel-plugins/>`_ and      | 
+|     |          | create a new environment from scratch.                                              |
++-----+----------+-------------------------------------------------------------------------------------+
+
+Versioning scheme
+~~~~~~~~~~~~~~~~~
+
+* Versioning does not support the ``.fp`` plugins. The user must download and
+  install the ``.fp`` plugin from scratch.
+* For RPM plugins, the versioning is as follows:
+
+.. image:: /_images/deliverables/scr_plugin_versioning.png
+   :width: 70%
+   :align: center
+
+.. note::
+     Change the versioning scheme for customized packages to
+     have a clear indicator which package is installed - the official
+     Mirantis OpenStack or customized ones. Otherwise, check the
+     Python files to understand which package is actually installed.

plugindocs/fuel-plugin-sdk-guide/reference/files/metadata.rst

@@ -47,8 +47,10 @@ Example:
 			deployment_scripts_path: deployment_scripts/
 			repository_path: repositories/ubuntu
 
-	# Version of plugin package
+	# Version of the plugin package
 	package_version: '4.0.0'
+	# Version of the plugin build
+	build_version: '1476097405'
 
 Fields:
 
@@ -58,7 +60,7 @@ Fields:
      underscore ``_``.
    * ``title`` -- Human-readable plugin name displayed on the Fuel web UI.
    * ``version`` -- Plugin version. For guidelines, see
-     `Semantic Versioning 2.0.0 <http://semver.org/>`_.
+     :ref:`plugin_versioning_system`.
    * ``fuel_version`` -- The Fuel version that your plugin is compatible with.
      Currently, the builder verifies ``fuel_version`` only against
      ``package_version``. The ``package_version`` field must be supported
@@ -106,3 +108,5 @@ Fields:
      +---------------+-------+-------+-------+-------+-------+
      | Fuel          | 6.0   | 6.1   | 7.0   | 8.0   | 9.0   |
      +---------------+-------+-------+-------+-------+-------+
+   * ``build_version`` -- A version of the build that allows to iterate package
+     version without updating the plugin version.