Skip to content

Contributing

This section is for people changing UnderStack itself, rather than deploying or
operating it.

This front door is new and incomplete

Most contributor documentation still lives in README.md and
DEVELOPMENT.md files next to the code. This page links to the main entry
points until that material is consolidated here.

Start here

  • RELEASING.md
    — how release notes and tags work. Read this before opening a pull request
    that changes anything an operator has to react to: such a pull request needs a
    changelog.d/ fragment, and CI enforces it.
  • Adding and Removing an Application — how a
    component becomes an ArgoCD Application.
  • Writing Ironic Drivers and Interfaces — how to add
    a new hardware type or interface to ironic-understack, starting from no
    Ironic knowledge.
  • Design and Background — why the project is shaped the
    way it is, starting with why we diverge from upstream OpenStack Helm.

Development environments

Each language and package keeps its own setup instructions with the code. These
links open the current version on GitHub:

Area Entry points
Python packages Ironic, Neutron, Nova, workflows, OpenStack sync
Go operators and CLIs understackctl, dexop, nautobotop, Ironic hardware exporter
Helm charts ArgoCD UnderStack chart, site workflows
Ansible Playbooks and roles
Containers Ironic, Nautobot, Neutron, Nova
End-to-end tests understack-tests

Python packages use uv with pytest and ruff;
Go projects use a Makefile with golangci-lint. Run the checks for the area
you touched before opening a pull request.

Documentation

The site is built with properdocs
from properdocs.yml:

make docs-local   # build and serve on http://127.0.0.1:8001
make docs         # build with --strict, as CI does

Two things to know before you add a page:

  • Every page under docs/ must appear in nav:. validation.omitted_files
    plus --strict makes an unlisted page a build failure. There is no way to ship
    a page that is not in the navigation, which is deliberate — it is what keeps
    orphans out.
  • Some pages are generated, and are gitignored rather than committed:
    docs/workflows/ (from the Argo templates), the neutron sample config, and
    docs/release-notes/unreleased.md (from changelog.d/). Use make docs
    rather than calling properdocs build directly, or the generated pages will be
    missing and --strict will fail.