diff --git a/README.rst b/README.rst
index 71e185f..c859ddd 100644
--- a/README.rst
+++ b/README.rst
@@ -94,6 +94,45 @@
 .. _testr: https://testrepository.readthedocs.org/en/latest/MANUAL.html
 .. _ostestr: http://docs.openstack.org/developer/os-testr/
 
+Library
+-------
+Tempest exposes a library interface. This interface is a stable interface and
+should be backwards compatible (including backwards compatibility with the
+old tempest-lib package, with the exception of the import). If you plan to
+directly consume tempest in your project you should only import code from the
+tempest library interface, other pieces of tempest do not have the same
+stable interface and there are no guarantees on the Python API unless otherwise
+stated.
+
+For more details refer to the library documentation here: :ref:`library`
+
+Release Versioning
+------------------
+Tempest's released versions are broken into 2 sets of information. Depending on
+how you intend to consume tempest you might need
+
+The version is a set of 3 numbers:
+
+X.Y.Z
+
+While this is almost `semver`_ like, the way versioning is handled is slightly
+different:
+
+X is used to represent the supported OpenStack releases for tempest tests
+in-tree, and to signify major feature changes to tempest. It's a monotonically
+increasing integer where each version either indicates a new supported OpenStack
+release, the drop of support for an OpenStack release (which will coincide with
+the upstream stable branch going EOL), or a major feature lands (or is removed)
+from tempest.
+
+Y.Z is used to represent library interface changes. This is treated the same
+way as minor and patch versions from `semver`_ but only for the library
+interface. When Y is incremented we've added functionality to the library
+interface and when Z is incremented it's a bug fix release for the library.
+Also note that both Y and Z are reset to 0 at each increment of X.
+
+.. _semver: http://semver.org/
+
 Configuration
 -------------
 
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index e428592..524c0fa 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -139,6 +139,11 @@
  #. ``alt_password``
  #. ``alt_tenant_name``
 
+If using Identity API v3, use the ``domain_name`` option to specify a
+domain other than the default domain.  The ``auth_version`` setting is
+used to switch between v2 (``v2``) or v3 (``v3``) versions of the Identity
+API.
+
 And in the ``auth`` section:
 
  #. ``use_dynamic_credentials = False``
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 32e6e51..17def1c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -11,6 +11,7 @@
    HACKING
    REVIEWING
    plugin
+   library
 
 ------------
 Field Guides
diff --git a/doc/source/library.rst b/doc/source/library.rst
new file mode 100644
index 0000000..24ead08
--- /dev/null
+++ b/doc/source/library.rst
@@ -0,0 +1,68 @@
+.. _library:
+
+Tempest Library Doucmentation
+=============================
+
+Tempest provides a stable library interface that provides external tools or
+test suites an interface for reusing pieces of tempest code. Any public
+interface that lives in tempest/lib in the tempest repo is treated as a stable
+public interface and it should be safe to external consume that. Every effort
+goes into maintaining backwards compatibility with any change. Just as with
+tempest-lib the library is self contained and doesn't have any dependency on
+other tempest internals outside of lib. (including no usage of tempest
+configuration)
+
+Stability
+---------
+Just as tempest-lib before it any code that lives in tempest/lib will be treated
+as a stable interface, nothing has changed in regards to interface stability.
+This means that any public interface under the tempest/lib directory is
+expected to be a stable interface suitable for public consumption. However, for
+any interfaces outside of tempest/lib in the tempest tree (unless otherwise
+noted) or any private interfaces the same stability guarantees don't apply.
+
+Adding Interfaces
+'''''''''''''''''
+When adding an interface to tempest/lib we have to make sure there are no
+dependencies on any pieces of tempest outside of tempest/lib. This means if
+for example there is a dependency on the configuration file we need remove that.
+The other aspect when adding an interface is to make sure it's really an
+interface ready for external consumption and something we want to commit to
+supporting.
+
+Making changes
+''''''''''''''
+When making changes to tempest/lib you have to be conscious of the effect of
+any changes on external consumers. If your proposed changeset will change the
+default behaviour of any interface, or make something which previously worked
+not after your change, then it is not acceptable. Every effort needs to go into
+preserving backwards compatibility in changes.
+
+Reviewing
+'''''''''
+When reviewing a proposed change to tempest/lib code we need to be careful to
+ensure that we don't break backwards compatibility. For patches that change
+existing interfaces we have to be careful to make sure we don't break any
+external consumers. Some common red flags are:
+
+ * a change to an existing API requires a change outside the library directory
+   where the interface is being consumed
+ * a unit test has to be significantly changed to make the proposed change pass
+
+Testing
+'''''''
+When adding a new interface to the library we need to at a minimum have unit
+test coverage. A proposed change to add an interface to tempest/lib that
+doesn't have unit tests shouldn't be accepted. Ideally these unit tests will
+provide sufficient coverage to ensure a stable interface moving forward.
+
+Current Library APIs
+--------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   library/cli
+   library/decorators
+   library/rest_client
+   library/utils
diff --git a/doc/source/library/cli.rst b/doc/source/library/cli.rst
new file mode 100644
index 0000000..6bd7881
--- /dev/null
+++ b/doc/source/library/cli.rst
@@ -0,0 +1,18 @@
+.. _cli:
+
+CLI Testing Framework Usage
+===========================
+
+-------------------
+The cli.base module
+-------------------
+
+.. automodule:: tempest.lib.cli.base
+   :members:
+
+----------------------------
+The cli.output_parser module
+----------------------------
+
+.. automodule:: tempest.lib.cli.output_parser
+   :members:
diff --git a/doc/source/library/decorators.rst b/doc/source/library/decorators.rst
new file mode 100644
index 0000000..a173967
--- /dev/null
+++ b/doc/source/library/decorators.rst
@@ -0,0 +1,13 @@
+.. _decorators:
+
+Decorators Usage Guide
+======================
+
+---------------------
+The decorators module
+---------------------
+
+.. automodule:: tempest.lib.decorators
+   :members:
+
+
diff --git a/doc/source/library/rest_client.rst b/doc/source/library/rest_client.rst
new file mode 100644
index 0000000..3045694
--- /dev/null
+++ b/doc/source/library/rest_client.rst
@@ -0,0 +1,11 @@
+.. _rest_client:
+
+Rest Client Usage
+=================
+
+----------------------
+The rest_client module
+----------------------
+
+.. automodule:: tempest.lib.common.rest_client
+   :members:
diff --git a/doc/source/library/utils.rst b/doc/source/library/utils.rst
new file mode 100644
index 0000000..bc2f79b
--- /dev/null
+++ b/doc/source/library/utils.rst
@@ -0,0 +1,11 @@
+.. _utils:
+
+Utils Usage
+===========
+
+---------------
+The misc module
+---------------
+
+.. automodule:: tempest.lib.common.utils.misc
+   :members:
diff --git a/requirements.txt b/requirements.txt
index 46ebbc5..23357fd 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -11,12 +11,12 @@
 netaddr!=0.7.16,>=0.7.12 # BSD
 testrepository>=0.0.18 # Apache-2.0/BSD
 pyOpenSSL>=0.14 # Apache-2.0
-oslo.concurrency>=2.3.0 # Apache-2.0
-oslo.config>=3.4.0 # Apache-2.0
+oslo.concurrency>=3.5.0 # Apache-2.0
+oslo.config>=3.7.0 # Apache-2.0
 oslo.i18n>=2.1.0 # Apache-2.0
 oslo.log>=1.14.0 # Apache-2.0
 oslo.serialization>=1.10.0 # Apache-2.0
-oslo.utils>=3.4.0 # Apache-2.0
+oslo.utils>=3.5.0 # Apache-2.0
 six>=1.9.0 # MIT
 iso8601>=0.1.9 # MIT
 fixtures>=1.3.1 # Apache-2.0/BSD
diff --git a/tempest/api/compute/images/test_images_negative.py b/tempest/api/compute/images/test_images_negative.py
index 63ba650..e91944f 100644
--- a/tempest/api/compute/images/test_images_negative.py
+++ b/tempest/api/compute/images/test_images_negative.py
@@ -67,7 +67,7 @@
         resp = {}
         resp['status'] = None
         self.assertRaises(lib_exc.NotFound, self.create_image_from_server,
-                          '!@$%^&*()', name=name, meta=meta)
+                          '!@$^&*()', name=name, meta=meta)
 
     @test.attr(type=['negative'])
     @test.idempotent_id('ec176029-73dc-4037-8d72-2e4ff60cf538')
diff --git a/tempest/cmd/account_generator.py b/tempest/cmd/account_generator.py
index df2d4b5..b95111a 100755
--- a/tempest/cmd/account_generator.py
+++ b/tempest/cmd/account_generator.py
@@ -480,8 +480,8 @@
 def main(opts=None):
     setup_logging()
     if not opts:
-        LOG.warn("Use of: 'tempest-account-generator' is deprecated, "
-                 "please use: 'tempest account-generator'")
+        LOG.warning("Use of: 'tempest-account-generator' is deprecated, "
+                    "please use: 'tempest account-generator'")
         opts = get_options()
     if opts.config_file:
         config.CONF.set_config_path(opts.config_file)
diff --git a/tempest/config.py b/tempest/config.py
index b062201..0e1b273 100644
--- a/tempest/config.py
+++ b/tempest/config.py
@@ -1027,11 +1027,6 @@
                default='cirros-0.3.1-x86_64-vmlinuz',
                help='AKI image file name',
                deprecated_for_removal=True),
-    cfg.IntOpt(
-        'large_ops_number',
-        default=0,
-        help="specifies how many resources to request at once. Used "
-        "for large operations testing."),
     # TODO(yfried): add support for dhcpcd
     cfg.StrOpt('dhcp_client',
                default='udhcpc',
diff --git a/tempest/scenario/test_large_ops.py b/tempest/scenario/test_large_ops.py
deleted file mode 100644
index 9ed831c..0000000
--- a/tempest/scenario/test_large_ops.py
+++ /dev/null
@@ -1,133 +0,0 @@
-# Copyright 2013 NEC Corporation
-# All Rights Reserved.
-#
-#    Licensed under the Apache License, Version 2.0 (the "License"); you may
-#    not use this file except in compliance with the License. You may obtain
-#    a copy of the License at
-#
-#         http://www.apache.org/licenses/LICENSE-2.0
-#
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#    License for the specific language governing permissions and limitations
-#    under the License.
-
-from tempest.common import fixed_network
-from tempest.common.utils import data_utils
-from tempest.common import waiters
-from tempest import config
-from tempest.lib import exceptions as lib_exc
-from tempest.scenario import manager
-from tempest import test
-
-CONF = config.CONF
-
-
-class TestLargeOpsScenario(manager.ScenarioTest):
-
-    """Test large operations.
-
-    This test below:
-    * Spin up multiple instances in one nova call, and repeat three times
-    * as a regular user
-    * TODO: same thing for cinder
-
-    """
-
-    @classmethod
-    def skip_checks(cls):
-        super(TestLargeOpsScenario, cls).skip_checks()
-        if CONF.scenario.large_ops_number < 1:
-            raise cls.skipException("large_ops_number not set to multiple "
-                                    "instances")
-
-    @classmethod
-    def setup_credentials(cls):
-        cls.set_network_resources()
-        super(TestLargeOpsScenario, cls).setup_credentials()
-
-    @classmethod
-    def resource_setup(cls):
-        super(TestLargeOpsScenario, cls).resource_setup()
-        # list of cleanup calls to be executed in reverse order
-        cls._cleanup_resources = []
-
-    @classmethod
-    def resource_cleanup(cls):
-        while cls._cleanup_resources:
-            function, args, kwargs = cls._cleanup_resources.pop(-1)
-            try:
-                function(*args, **kwargs)
-            except lib_exc.NotFound:
-                pass
-        super(TestLargeOpsScenario, cls).resource_cleanup()
-
-    @classmethod
-    def addCleanupClass(cls, function, *arguments, **keywordArguments):
-        cls._cleanup_resources.append((function, arguments, keywordArguments))
-
-    def _wait_for_server_status(self, status):
-        for server in self.servers:
-            # Make sure nova list keeps working throughout the build process
-            self.servers_client.list_servers()
-            waiters.wait_for_server_status(self.servers_client,
-                                           server['id'], status)
-
-    def nova_boot(self, image):
-        name = data_utils.rand_name('scenario-server')
-        flavor_id = CONF.compute.flavor_ref
-        # Explicitly create secgroup to avoid cleanup at the end of testcases.
-        # Since no traffic is tested, we don't need to actually add rules to
-        # secgroup
-        secgroup = self.compute_security_groups_client.create_security_group(
-            name='secgroup-%s' % name,
-            description='secgroup-desc-%s' % name)['security_group']
-        self.addCleanupClass(
-            self.compute_security_groups_client.delete_security_group,
-            secgroup['id'])
-        create_kwargs = {
-            'min_count': CONF.scenario.large_ops_number,
-            'security_groups': [{'name': secgroup['name']}]
-            }
-        network = self.get_tenant_network()
-        create_kwargs = fixed_network.set_networks_kwarg(network,
-                                                         create_kwargs)
-        self.servers_client.create_server(
-            name=name,
-            imageRef=image,
-            flavorRef=flavor_id,
-            **create_kwargs)
-        # needed because of bug 1199788
-        params = {'name': name}
-        server_list = self.servers_client.list_servers(**params)
-        self.servers = server_list['servers']
-        for server in self.servers:
-            # after deleting all servers - wait for all servers to clear
-            # before cleanup continues
-            self.addCleanupClass(waiters.wait_for_server_termination,
-                                 self.servers_client,
-                                 server['id'])
-        for server in self.servers:
-            self.addCleanupClass(self.servers_client.delete_server,
-                                 server['id'])
-        self._wait_for_server_status('ACTIVE')
-
-    def _large_ops_scenario(self):
-        image = self.glance_image_create()
-        self.nova_boot(image)
-
-    @test.idempotent_id('14ba0e78-2ed9-4d17-9659-a48f4756ecb3')
-    @test.services('compute', 'image')
-    def test_large_ops_scenario_1(self):
-        self._large_ops_scenario()
-
-    @test.idempotent_id('b9b79b88-32aa-42db-8f8f-dcc8f4b4ccfe')
-    @test.services('compute', 'image')
-    def test_large_ops_scenario_2(self):
-        self._large_ops_scenario()
-
-    @test.idempotent_id('3aab7e82-2de3-419a-9da1-9f3a070668fb')
-    @test.services('compute', 'image')
-    def test_large_ops_scenario_3(self):
-        self._large_ops_scenario()
diff --git a/tempest/stress/stressaction.py b/tempest/stress/stressaction.py
index c8bd652..cf0a08a 100644
--- a/tempest/stress/stressaction.py
+++ b/tempest/stress/stressaction.py
@@ -85,8 +85,8 @@
             finally:
                 shared_statistic['runs'] += 1
                 if self.stop_on_error and (shared_statistic['fails'] > 1):
-                    self.logger.warn("Stop process due to"
-                                     "\"stop-on-error\" argument")
+                    self.logger.warning("Stop process due to"
+                                        "\"stop-on-error\" argument")
                     self.tearDown()
                     sys.exit(1)
 
diff --git a/test-requirements.txt b/test-requirements.txt
index a92adb0..be3a4f1 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -6,7 +6,7 @@
 sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2 # BSD
 python-subunit>=0.0.18 # Apache-2.0/BSD
 oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0
-reno>=0.1.1  # Apache2
+reno>=0.1.1 # Apache2
 mox>=0.5.3 # Apache-2.0
 mock>=1.2 # BSD
 coverage>=3.6 # Apache-2.0
diff --git a/tox.ini b/tox.ini
index 96a97f4..28dfe8b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -70,14 +70,6 @@
   find . -type f -name "*.pyc" -delete
   bash tools/pretty_tox_serial.sh '(?!.*\[.*\bslow\b.*\])(^tempest\.(api|scenario|thirdparty)) {posargs}'
 
-[testenv:large-ops]
-sitepackages = {[tempestenv]sitepackages}
-setenv = {[tempestenv]setenv}
-deps = {[tempestenv]deps}
-commands =
-  find . -type f -name "*.pyc" -delete
-  python setup.py testr --slowest --testr-args='tempest.scenario.test_large_ops {posargs}'
-
 [testenv:smoke]
 sitepackages = {[tempestenv]sitepackages}
 setenv = {[tempestenv]setenv}