diff --git a/README.rst b/README.rst index 71e185fda8..c859ddd2f0 100644 --- a/README.rst +++ b/README.rst @@ -94,6 +94,45 @@ as it is simpler, and quicker to work with. .. _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/index.rst b/doc/source/index.rst index 32e6e51fb7..17def1c84f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,6 +11,7 @@ Contents: HACKING REVIEWING plugin + library ------------ Field Guides diff --git a/doc/source/library.rst b/doc/source/library.rst new file mode 100644 index 0000000000..24ead08ec7 --- /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 0000000000..6bd78810dd --- /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 0000000000..a1739678e1 --- /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 0000000000..3045694f5e --- /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 0000000000..bc2f79b067 --- /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: