Merge pull request #32487 from terminalmage/epoch-documentation

Add explanation of nonzero epoch requirement to pkg.installed state documentation

doc/topics/releases/2015.8.7.rst

@@ -11,6 +11,22 @@ Salt 2015.8.7 Release Notes
 Changes for v2015.8.4..v2015.8.7
 --------------------------------
 
+For :py:mod:`pkg.installed <salt.states.pkg.installed>` states, on Linux
+distributions which use yum/dnf, packages which have a non-zero epoch in the
+version number now require this epoch to be included when specifying an exact
+version for a package. For example:
+
+.. code-block:: yaml
+
+    vim-enhanced:
+      pkg.installed:
+        - version: 2:7.4.160-1.el7
+
+The :py:mod:`pkg.latest_version <salt.modules.yumpkg.latest_version>` and
+:py:mod:`pkg.list_repo_pkgs <salt.modules.yumpkg.list_repo_pkgs>` functions can
+be used to get the correct version string to use, as they will now contain the
+epoch when it is non-zero.
+
 Extended changelog courtesy of Todd Stansell (https://github.com/tjstansell/salt-changelogs):
 
 *Generated at: 2016-02-11T22:13:51Z*

salt/states/pkg.py

@@ -613,9 +613,22 @@ def installed(
 
         .. code-block:: bash
 
-            # salt myminion pkg.latest_version httpd
+            # salt myminion pkg.latest_version vim-enhanced
             myminion:
-                2.2.15-30.el6.centos
+                2:7.4.160-1.el7
+
+        .. important::
+            As of version 2015.8.7, for distros which use yum/dnf, packages
+            which have a version with a nonzero epoch (that is, versions which
+            start with a number followed by a colon like in the example above)
+            must have the epoch included when specifying the version number.
+            For example:
+
+            .. code-block:: yaml
+
+                vim-enhanced:
+                  pkg.installed:
+                    - version: 2:7.4.160-1.el7
 
         Also, while this function is not yet implemented for all pkg frontends,
         :mod:`pkg.list_repo_pkgs <salt.modules.yumpkg.list_repo_pkgs>` will