diff --git a/doc/source/compatibility.rst b/doc/source/compatibility.rst
new file mode 100644
index 00000000..f93aa716
--- /dev/null
+++ b/doc/source/compatibility.rst
@@ -0,0 +1,46 @@
+..
+    The name of this document and the anchor in this document must be
+    treated as a stable API.  Links to this document are coded into
+    pbr and deployed versions of pbr will refer users to this document
+    in the case of certain errors.
+    Ensure any link you use in PBR is defined via a ref with .. _name.
+
+
+===================
+Compatibility Notes
+===================
+
+Useful notes about errors users may encounter when features cannot be
+supported on older versions of setuptools / pip / wheel.
+
+
+setuptools
+==========
+
+
+.. _evaluate-marker:
+
+evaluate_marker
+---------------
+
+evaluate_markers may run into issues with the '>', '>=', '<', and '<='
+operators if the installed version of setuptools is less than 17.1.  Projects
+using these operators with markers should specify a minimum version of 17.1
+for setuptools.
+
+
+pip
+===
+
+markers
+-------
+
+For versions of pip < 7 with pbr < 1.9, dependencies that use markers will not
+be installed.  Projects using pbr and markers should set a minimum version of
+1.9 for pbr.
+
+
+Recommended setup.py
+====================
+
+:ref:`setup_py`.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b09e8689..a76ce2e6 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -144,19 +144,21 @@ Usage
 ``setuptools.setup()``. While the normal setuptools facilities are available,
 pbr makes it possible to express them through static data files.
 
+.. _setup_py:
+
 setup.py
 --------
 
 `pbr` only requires a minimal `setup.py` file compared to a standard setuptools
 project. This is because most configuration is located in static configuration
-files. This minimal `setup.py` file should look something like this::
+files. This recommended minimal `setup.py` file should look something like this::
 
     #!/usr/bin/env python
 
     from setuptools import setup
 
     setup(
-        setup_requires=['pbr'],
+        setup_requires=['pbr>=1.9', 'setuptools>=17.1'],
         pbr=True,
     )
 
@@ -395,6 +397,7 @@ Additional Docs
    packagers
    semver
    testing
+   compatibility
 
 Indices and tables
 ==================
diff --git a/pbr/tests/test_util.py b/pbr/tests/test_util.py
index 70f1e901..71ea92fb 100644
--- a/pbr/tests/test_util.py
+++ b/pbr/tests/test_util.py
@@ -45,10 +45,11 @@ class TestExtrasRequireParsingScenarios(base.BaseTestCase):
                     foo:python_version=='2.6'
                     bar
                     baz<1.6 :python_version=='2.6'
+                    zaz :python_version>'1.0'
                 """,
             'expected_extra_requires': {
                 "test:(python_version=='2.6')": ['foo', 'baz<1.6'],
-                "test": ['bar']}}),
+                "test": ['bar', 'zaz']}}),
         ('no_extras', {
             'config_text': """
             [metadata]
@@ -73,3 +74,10 @@ class TestExtrasRequireParsingScenarios(base.BaseTestCase):
 
         self.assertEqual(self.expected_extra_requires,
                          kwargs['extras_require'])
+
+
+class TestInvalidMarkers(base.BaseTestCase):
+
+    def test_invalid_marker_raises_error(self):
+        config = {'extras': {'test': "foo :bad_marker>'1.0'"}}
+        self.assertRaises(SyntaxError, util.setup_cfg_to_setup_kwargs, config)
diff --git a/pbr/util.py b/pbr/util.py
index cd7397fd..daad1386 100644
--- a/pbr/util.py
+++ b/pbr/util.py
@@ -431,7 +431,13 @@ def setup_cfg_to_setup_kwargs(config, script_args=()):
                         if pkg_resources.evaluate_marker('(%s)' % env_marker):
                             extras_key = req_group
                     except SyntaxError:
-                        pass
+                        log.error(
+                            "Marker evaluation failed, see the following "
+                            "error.  For more information see: "
+                            "http://docs.openstack.org/"
+                            "developer/pbr/compatibility.html#evaluate-marker"
+                        )
+                        raise
             else:
                 extras_key = req_group
             extras_require.setdefault(extras_key, []).append(requirement)