=================
How To Contribute
=================

Basics
~~~~~~

* Our source code is hosted on `OpenStack GitHub`_, but please do not send pull
  requests there.

* Please follow usual OpenStack `Gerrit Workflow`_ to submit a patch.

* Update change log in README.rst on any significant change.

* It goes without saying that any code change should by accompanied by unit
  tests.

* Note the branch you're proposing changes to. ``master`` is the current focus
  of development, use ``stable/VERSION`` for proposing an urgent fix, where
  ``VERSION`` is the current stable series. E.g. at the moment of writing the
  stable branch is ``stable/1.0``.

* Please file a launchpad_ blueprint for any significant code change and a bug
  for any significant bug fix.

.. _OpenStack GitHub: https://github.com/openstack/ironic-inspector
.. _Gerrit Workflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow
.. _launchpad: https://bugs.launchpad.net/ironic-inspector

Development Environment
~~~~~~~~~~~~~~~~~~~~~~~

First of all, install *tox* utility. It's likely to be in your distribution
repositories under name of ``python-tox``. Alternatively, you can install it
from PyPI.

Next checkout and create environments::

    git clone https://github.com/openstack/ironic-inspector.git
    cd ironic-inspector
    tox

Repeat *tox* command each time you need to run tests. If you don't have Python
interpreter of one of supported versions (currently 2.7 and 3.4), use
``-e`` flag to select only some environments, e.g.

::

    tox -e py27

.. note::
    Support for Python 3 is highly experimental, stay with Python 2 for the
    production environment for now.

There is a simple functional test that involves fetching the ramdisk from
Github::

    tox -e func

Run the service with::

    .tox/py27/bin/ironic-inspector --config-file example.conf

Of course you may have to modify ``example.conf`` to match your OpenStack
environment.

You can develop and test **ironic-inspector** using DevStack - see
`DevStack Support`_ for the current status.

DevStack Support
~~~~~~~~~~~~~~~~

`DevStack <http://docs.openstack.org/developer/devstack/>`_ provides a way to
quickly build full OpenStack development environment with requested
components. There is a plugin for installing **ironic-inspector** on DevStack.

Example local.conf
------------------

::

    [[local|localrc]]
    enable_service ironic ir-api ir-cond
    disable_service n-net n-novnc
    enable_service neutron q-svc q-agt q-dhcp q-l3 q-meta
    disable_service heat h-api h-api-cfn h-api-cw h-eng
    disable_service cinder c-sch c-api c-vol

    enable_plugin ironic-inspector https://github.com/openstack/ironic-inspector

    IRONIC_BAREMETAL_BASIC_OPS=True
    IRONIC_VM_COUNT=2
    IRONIC_VM_SPECS_RAM=1024
    IRONIC_DEPLOY_FLAVOR="fedora deploy-ironic"

    IRONIC_INSPECTOR_RAMDISK_FLAVOR="fedora ironic-discoverd-ramdisk"

    VIRT_DRIVER=ironic

    LOGDAYS=1
    LOGFILE=~/logs/stack.sh.log
    SCREEN_LOGDIR=~/logs/screen

    DEFAULT_INSTANCE_TYPE=baremetal
    TEMPEST_ALLOW_TENANT_ISOLATION=False

Notes
-----

* Replace "fedora" with whatever you have

* You need at least 1G of RAM for VMs, default value of 512 MB won't work

* Network configuration is pretty sensitive, better not to touch it
  without deep understanding

* This configuration disables Heat and Cinder, adjust it if you need these
  services

* Before restarting stack.sh::

    rm -rf /opt/stack/ironic-inspector

Test
----

There is a test script included::

    source devstack/openrc admin admin
    /opt/stack/ironic-inspector/devstack/exercise.sh

Usage
-----

Start introspection for a node manually::

    source devstack/openrc admin admin
    openstack baremetal introspection start <UUID>

Then check status via API::

    openstack baremetal introspection status <UUID>

Writing a Plugin
~~~~~~~~~~~~~~~~

**ironic-inspector** allows to hook your code into data processing chain after
introspection. Inherit ``ProcessingHook`` class defined in
`ironic_inspector.plugins.base
<https://github.com/openstack/ironic-inspector/blob/master/ironic_inspector/plugins/base.py>`_
module and overwrite any or both of the following methods:

``before_processing(node_info)``
    called before any data processing, providing the raw data. Each plugin in
    the chain can modify the data, so order in which plugins are loaded
    matters here. Returns nothing.
``before_update(node,ports,node_info)``
    called after node is found and ports are created, but before data is
    updated on a node. Returns JSON patches for node and ports to apply.
    Please refer to the docstring for details and examples.