openstack/tempest
Code Issues Proposed changes

Add note a section to lib doc about where to put plugins

Browse Source 
This commit adds a subsection to the creating a plugin section in the
plugin doc that tries to strongly advocate creating a separate python
package for tempest plugins for various reasons. This will hopefully
steer potential plugin authors towards doing this.

Change-Id: Id3c06381c0d8e79f59e50486a3c10b12bb977c51
This commit is contained in:
Matthew Treinish
2016-03-09 15:39:19 -05:00
parent e86fc5df1b
commit 00686f2fda
1 changed files with 31 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
doc/source/plugin.rst
View File

@@ -55,6 +55,37 @@ something like the following::
tempest.test_plugins =
plugin_name = module.path:PluginClass
Standalone Plugin vs In-repo Plugin
-----------------------------------
Since all that's required for a plugin to be detected by tempest is a valid
setuptools entry point in the proper namespace there is no difference from the
tempest perspective on either creating a separate python package to
house the plugin or adding the code to an existing python project. However,
there are tradeoffs to consider when deciding which approach to take when
creating a new plugin.
If you create a separate python project for your plugin this makes a lot of
things much easier. Firstly it makes packaging and versioning much simpler, you
can easily decouple the requirements for the plugin from the requirements for
the other project. It lets you version the plugin independently and maintain a
single version of the test code across project release boundaries (see the
`Branchless Tempest Spec`_ for more details on this). It also greatly
simplifies the install time story for external users. Instead of having to
install the right version of a project in the same python namespace as tempest
they simply need to pip install the plugin in that namespace. It also means
that users don't have to worry about inadvertently installing a tempest plugin
when they install another package.
.. _Branchless Tempest Spec: http://specs.openstack.org/openstack/qa-specs/specs/tempest/implemented/branchless-tempest.html
The sole advantage to integrating a plugin into an existing python project is
that it enables you to land code changes at the same time you land test changes
in the plugin. This reduces some of the burden on contributors by not having
to land 2 changes to add a new API feature and then test it and doing it as a
single combined commit.
Plugin Class
============