From 5d74e8ae6ecef428c6c18b651a3031d56a2e209b Mon Sep 17 00:00:00 2001
From: Ivan Kravets <me@ikravets.com>
Date: Mon, 4 Jan 2016 01:07:42 +0200
Subject: [PATCH] Improve docs for library.json "version" field

---
 docs/librarymanager/config.rst | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst
index 69669474..e49794d7 100644
--- a/docs/librarymanager/config.rst
+++ b/docs/librarymanager/config.rst
@@ -161,15 +161,25 @@ Example:
 A version of the current library source code.
 
 * Can contain a-z, digits, dots or dash.
-* `Semantic Versioning <http://semver.org>`_ is recommended.
+* `Semantic Versioning <http://semver.org>`_ IS RECOMMENDED.
 * A `CVS <http://en.wikipedia.org/wiki/Concurrent_Versions_System>`_
-  revision from the latest commit. Example: ``13`` (*SVN*) or first 10
-  chars of *SHA* digest ``e4564b7da4`` (*Git*).
+  revision from the latest commit.
+
+If :ref:`libjson_version` field is not defined and :ref:`libjson_repository`
+field is defined, then |PIOAPICR| will use the *CVS*-revision from the latest
+commit as "current version". For example, ``13`` (*SVN*) or first 10 chars of
+*SHA* digest ``e4564b7da4`` (*Git*).
+
+If :ref:`libjson_version` and :ref:`libjson_repository` fields are defined,
+then :ref:`libjson_version` has HIGHER PRIORITY. We recommend to use
+:ref:`libjson_version` field and specify the real release version. In other
+case, users will receive updates for library with each new commit to
+:ref:`libjson_repository`.
 
 .. note::
-    You can omit :ref:`libjson_version` field and define
-    :ref:`libjson_repository` field. In this case
-    |PIOAPICR| will use the *CVS*-revision from the latest commit.
+    |PIOAPICR| updates library only if:
+        - the :ref:`libjson_version` is changed
+        - ``library.json`` is modified
 
 Example: