From: armando-migliaccio Date: Tue, 3 Feb 2015 03:24:11 +0000 (-0800) Subject: Add section for DevStack Integration Strategies to the DevRef X-Git-Url: https://review.fuel-infra.org/gitweb?a=commitdiff_plain;h=c244e6b81e303790ccd167fdad0457bfa1e8a936;p=openstack-build%2Fneutron-build.git Add section for DevStack Integration Strategies to the DevRef Plugins may already have DevStack support, that may need to be revised according to the decomposition. If a plugin/driver does not have one, it is necessary to add it to ease the development effort. This section explains what DevStack integration options are available, in relation to the dev/test cycle and 3rd party CI systems. Links were not rendered correctly. So this patch takes care of that too. Partially implements blueprint: core-vendor-decomposition Change-Id: Ib12e38d775af1e5a840bd009c95dac4c982b9753 --- diff --git a/doc/source/devref/contribute.rst b/doc/source/devref/contribute.rst index b081a74ea..3759e65cd 100644 --- a/doc/source/devref/contribute.rst +++ b/doc/source/devref/contribute.rst @@ -37,6 +37,7 @@ Below, the following strategies will be documented: * Testing and Continuous Integration; * Defect Management; * Backport Management for plugin specific code; +* DevStack Integration; * Documentation; This document will then provide a working example on how to contribute @@ -163,12 +164,12 @@ precisely: Backport Management Strategies ------------------------------ -As outlined in the `Spec proposal http://specs.openstack.org/openstack/neutron-specs/specs/kilo/core-vendor-decomposition.html` +As outlined in the `Spec proposal `_ all new plugins and drivers will have to follow the contribution model described here. As for existing plugins and drivers, no in-tree features can be merged until some progress has been done to make the solution adhere to this model. That said, there is the question of critical fixes and/or backports -to `stable branches https://wiki.openstack.org/wiki/StableBranch`. The possible +to `stable branches `_. The possible scenarios are: * The decomposition just completed, we are in the cycle (X) where the decomposition @@ -196,6 +197,70 @@ scenarios are: of the maintainer to avoid introducing or modifying existing code that will ultimately be deprecated. +DevStack Integration Strategies +------------------------------- + +When developing and testing a new or existing plugin or driver, the aid provided +by DevStack is incredibly valuable: DevStack can help get all the software bits +installed, and configured correctly, and more importantly in a predictable way. +For DevStack integration there are a few options available, and they may or may not +make sense depending on whether you are contributing a new or existing plugin or +driver. + +If you are contributing a new plugin, the approach to choose should be based on +`Extras.d Hooks `_. +With the extra.d hooks, the DevStack integration is colocated with the vendor integration +library, and it leads to the greatest level of flexibility when dealing with DevStack based +dev/test deployments. + +Having said that, most Neutron Plugins developed in the past likely already have +integration with DevStack in the form of `neutron_plugins `_. +If the plugin is being decomposed in vendor integration plus vendor library, it would +be necessary to adjust the instructions provided in the neutron_plugin file to pull the +vendor library code as a new dependency. For instance, the instructions below: + + :: + + INSTALL_FROM_REQUIREMENTS=$(trueorfalse True INSTALL_FROM_REQUIREMENTS) + + if [[ "$INSTALL_FROM_REQUIREMENTS" == "False" ]]; then + git_clone $NEUTRON_LIB_REPO $NEUTRON_LIB_DIR $NEUTRON_LIB_BRANCH + setup_package $NEUTRON_LIB_DIR + else + # Retrieve the package from the vendor library's requirements.txt + plugin_package=$(cat $NEUTRON_LIB_REQUIREMENTS_FILE) + pip_install "$plugin_package" + fi + +could be placed in 'neutron_plugin_configure_service', ahead of the service +configuration. An alternative could be under the `third_party section +`_, +if available. This solution can be similarly exploited for both monolithic +plugins or ML2 mechanism drivers. The configuration of the plugin or driver itself can be +done by leveraging the extensibility mechanisms provided by `local.conf `_. In fact, since the .ini file for the vendor plugin or driver lives +in the Neutron tree, it is possible to do add the section below to local.conf: + + :: + + [[post-config|$THE_FILE_YOU_NEED_TO_CUSTOMIZE]] + + # Override your section config as you see fit + [DEFAULT] + verbose=True + +Which in turn it is going to edit the file with the options outlined in the post-config +section. + +The above mentioned approach, albeit valid, has the shortcoming of depending on DevStack's +explicit support for the plugin installation and configuration, and the plugin maintainer +is strongly encouraged to revise the existing DevStack integration, in order to evolve it +in an extras.d hooks based approach. + +One final consideration is worth making for 3rd party CI setups: if `Devstack Gate +`_ is used, it does provide hook +functions that can be executed at specific times of the devstack-gate-wrap script run. +For example, the `Neutron Functional job `_ uses them. For more details see `devstack-vm-gate-wrap.sh `_. + Documentation Strategies ------------------------ @@ -269,21 +334,21 @@ be the bare minimum you have to complete in order to get you off the ground. the previous step. In the latter case, you can do so by specifying the upstream section for your project in project-config/gerrit/project.yaml. Steps are documented on the - `Project Creators Manual http://docs.openstack.org/infra/manual/creators.html`. + `Project Creators Manual `_. * Ask for a Launchpad user to be assigned to the core team created. Steps are documented in - `this section http://docs.openstack.org/infra/manual/creators.html#update-the-gerrit-group-members`. + `this section `_. * Fix, fix, fix: at this point you have an external base to work on. You can develop against the new stackforge project, the same way you work with any other OpenStack project: you have pep8, docs, and python27 CI jobs that validate your patches when posted to Gerrit. For instance, one thing you would need to do is to define an entry point for your plugin or driver in your own setup.cfg similarly as to how it is done - `here https://github.com/stackforge/networking-odl/blob/master/setup.cfg#L31`. + `here `_. * Define an entry point for your plugin or driver in setup.cfg * Create 3rd Party CI account: if you do not already have one, follow instructions for - `3rd Party CI http://ci.openstack.org/third_party.html` to get one. + `3rd Party CI `_ to get one. * TODO(armax): ... The 'ODL ML2 Mechanism Driver' - example 1