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 Git hooks, Unit Testing Environment, and Integrated Testing Environments. 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 Testing Environment.
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.
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. |
|
Bifrost |
Used for testing Ironic standalone with minimal setup or using real hardware, or testing bifrost changes directly. |
|
Local |
Ironic services running locally, without any other OpenStack services. This can be useful for rapid prototyping, debugging, or testing database migrations. |
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 git git-review libffi-dev gettext ipmitool psmisc graphviz libjpeg-dev qemu-utils
RHEL/CentOS/Fedora:
sudo dnf install python3-devel openssl-devel python3-pip mysql-devel libxml2-devel libxslt-devel git git-review libffi-devel gettext ipmitool psmisc graphviz gcc libjpeg-turbo-devel qemu-img
openSUSE/SLE:
sudo zypper install git git-review libffi-devel libmysqlclient-devel libopenssl-devel libxml2-devel libxslt-devel python3-devel python-nose python3-pip gettext-runtime psmisc qemu-img
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.
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, |
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 |
docs |
Build and validate documentation. |
releasenotes |
Build and validate release notes using |
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. |
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.
Other tests¶
Ironic also has a number of tests built with Tempest. For more information about writing or running those tests, see Add Ironic Tempest Plugin.
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
