ironic/doc/source/contributor/dev-quickstart.rst

Developer Quick-Start

This is a quick walkthrough to get you started developing code for Ironic. This assumes you are already familiar with submitting code reviews to an OpenStack project. If you are not, please begin by following the steps in the OpenDev infra manual to get yourself familiar with the general git workflow we use.

This guide is primarily technical in nature; for information on how the Ironic team organizes work, please see Ironic's contribution guide.

This document covers githooks, unit, and integrated. New contributors are recommended to setup git hooks, then continue with unit tests.

Git hooks

Ironic uses multiple software packages to ensure code is styled as expected. A convenient way to ensure your code complies with these rules is via the use of pre-commit.

To configure your environment for automatic checking of code spelling and linting before commit, install pre-commit:

pip install --user pre-commit cd /path/to/ironic/checkout pre-commit install --allow-missing-config

Now, before any commit, any changed lines will be run through our pre-commit checks. Contributors are still encouraged to run pep8 and codespell tox environments before pushing code as an extra check.

More information about running tests in tox available in unit.

Integrated Testing Environments

The ultimate in development environments for Ironic is a working system, with mock bare metal hardware and a fully functional API service. There are three ways to get environment, listed below.

Note

These environments may use automation that assume you are running on a VM. Please do not use these environments on a system that you are not willing to have wiped and reinstalled when complete.

Testing Environments

Environment	Description/Uses	How-To
Devstack	Useful for testing Ironic with other OpenStack services. Also the environment required for running or building Ironic's tempest tests. Recommended for new contributors.	devstack-guide
Bifrost	Used for testing Ironic standalone with minimal setup or using real hardware, or testing bifrost changes directly.	bifrost-dev-guide
Local	Ironic services running locally, without any other OpenStack services. This can be useful for rapid prototyping, debugging, or testing database migrations.	local-dev-guide

Unit Testing Environment

For most people, unit testing is the quickest and easiest way to check the validity of a change. Unlike a fully integrated testing environment, unit tests can generally be safely run on a developer's workstation.

Ironic uses tox to orchestrate unit tests and documentation building. Contributors are strongly encouraged to validate code passes unit tests under a supported version of python before pushing up a change. See the Project Testing Interface for the exact versions of python supported currently.

System Prerequisites

The following packages cover the prerequisites for a local development environment on most current distributions.

• Ubuntu/Debian:

  sudo apt-get install build-essential python3-dev libssl-dev python3-pip libmysqlclient-dev libxml2-dev libxslt-dev libpq-dev git git-review libffi-dev gettext ipmitool psmisc graphviz libjpeg-dev

• RHEL/CentOS/Fedora:

  sudo dnf install python3-devel openssl-devel python3-pip mysql-devel libxml2-devel libxslt-devel postgresql-devel git git-review libffi-devel gettext ipmitool psmisc graphviz gcc libjpeg-turbo-devel

• openSUSE/SLE:

  sudo zypper install git git-review libffi-devel libmysqlclient-devel libopenssl-devel libxml2-devel libxslt-devel postgresql-devel python3-devel python-nose python3-pip gettext-runtime psmisc

To run the tests locally, it is a requirement that your terminal emulator supports unicode with the en_US.UTF8 locale. If you use locale-gen to manage your locales, make sure you have enabled en_US.UTF8 in /etc/locale.gen and rerun locale-gen.

Python Prerequisites

We suggest to use at least tox 3.9, if your distribution has an older version, you can install it using pip system-wise or better per user using the --user option that by default will install the binary under $HOME/.local/bin, so you need to be sure to have that path in $PATH; for example:

pip install tox --user

will install tox as ~/.local/bin/tox

You may need to explicitly upgrade virtualenv if you've installed the one from your OS distribution and it is too old (tox will complain). You can upgrade it individually, if you need to:

pip install --upgrade virtualenv --user

Running Unit Tests Locally

If you haven't already, Ironic source code should be pulled directly from git:

# from a user-writable directory, usually $HOME or $HOME/dev
git clone https://opendev.org/openstack/ironic
cd ironic

Most of the time, you will want to run codespell, unit tests, and pep8 checks. This can be done with the following command:

tox -e codespell,pep8,py3

Ironic has multiple test environments that can be run by tox. An incomplete list of environments and what they do is below. Please reference the tox.ini file in the project you're working on for a complete, up-to-date list.

Tox Environments

Environment	Description
pep8	Run style checks on code, documentation, and release notes.
codespell	Check code against a list of known-misspelled words.
py<version>	Run unit tests with the specified python version. For example, py310 will run the unit tests with python 3.10.
unit-with-driver-libs	Run unit tests with the default python3 on the system, but also includes driver-specific libraries and the tests they enable.
mysql-migrations	Run MySQL database migration unit tests. Setup database first using tools/test-setup.sh in Ironic repo.
docs	Build and validate documentation.
releasenotes	Build and validate release notes using reno.
api-ref	Build and validate API reference documentation.
genconfig	Generates example configuration file.
genpolicy	Generates example policy configuration file.
venv	Creates a venv, with dependencies installed, for running commands in e.g. tox -evenv -- reno new my-release-note

You may also pass options to the test programs using positional arguments. To run a specific unit test, this passes the desired test (regex string) to stestr:

# run a specific test for Python 3.10
tox -epy310 -- test_conductor

Debugging unit tests

In order to break into the debugger from a unit test we need to insert a breaking point to the code:

import pdb; pdb.set_trace()

Then run tox with the debug environment as one of the following:

tox -e debug
tox -e debug test_file_name
tox -e debug test_file_name.TestClass
tox -e debug test_file_name.TestClass.test_name

For more information see the oslotest documentation <user/features.html#debugging-with-oslo-debug-helper>.

Other tests

Ironic also has a number of tests built with Tempest. For more information about writing or running those tests, see tempest.

OSProfiler Tracing in Ironic

OSProfiler is an OpenStack cross-project profiling library. It is being used among OpenStack projects to look at performance issues and detect bottlenecks. For details on how OSProfiler works and how to use it in ironic, please refer to OSProfiler Support Documentation.

Building developer documentation

If you would like to build the documentation locally, eg. to test your documentation changes before uploading them for review, run these commands to build the documentation set:

• On the machine with the ironic checkout:

  # change into the ironic source code directory
  cd ~/ironic
  
  # build the docs
  tox -edocs

To view the built documentation locally, open up the top level index.html in your browser. For an example user named bob with the Ironic checkout in their homedir, the URL to put in the browser would be:

file:///home/bob/ironic/doc/build/html/index.html

If you're building docs on a remote VM, you can use python's SimpleHTTPServer to setup a quick webserver to check your docs build:

# Change directory to the newly built HTML files
cd ~/ironic/doc/build/html/

# Create a server using python on port 8000
python -m SimpleHTTPServer 8000

# Now use your browser to open the top-level index.html located at:
http://remote_ip:8000