From 823a7c93bd2739986888619dcf19fdce521307ad Mon Sep 17 00:00:00 2001
From: Sharpz7 <adam.mcarthur62@gmail.com>
Date: Fri, 4 Oct 2024 21:12:28 +0000
Subject: [PATCH] Added Localdev Docs on changing microversion

Added some documentaition that details how to change the ironic localdev microversion for testing purposes.

Rendered View: https://files.mcaq.me/944ch.png

Change-Id: I1e21a12ad1413046a41f856ddf229e399f82523a
---
 doc/source/contributor/local-dev-guide.rst | 50 ++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/doc/source/contributor/local-dev-guide.rst b/doc/source/contributor/local-dev-guide.rst
index c7d40d8d0c..f4e05bac37 100644
--- a/doc/source/contributor/local-dev-guide.rst
+++ b/doc/source/contributor/local-dev-guide.rst
@@ -218,3 +218,53 @@ help with that, but are not an exhaustive troubleshooting guide::
   . .tox/local-ironic-dev/bin/activate
   pip install -U -e .
 
+Changing the Ironic Localdev Microversion
+_________________________________________
+
+Localdev supports testing against a specific microversion, which is useful
+for testing backwards compatibility or evaluating external tools with
+different versions of the API.
+
+Steps to Change the Microversion
+--------------------------------
+
+To change the microversion, modify the ``ironic.conf.localdev`` file.
+Instead of directly modifying the microversion, you should set the release
+version corresponding to the microversion you intend to test. The mappings
+between release versions and microversions (for the REST API) are maintained
+in ``ironic/common/release_mappings.py``.
+
+For example, to set the microversion to **16.2**, you would adjust
+the ``pin_release_version`` parameter:
+
+.. code-block:: ini
+
+    [DEFAULT]
+    # Set the release version corresponding to microversion 16.2
+    pin_release_version = 16.2
+
+You can review the full configuration and release version mappings
+in the `sample configuration documentation <https://docs.openstack.org/ironic/latest/configuration/sample-config.html>`_.
+
+Resetting Localdev Setup
+------------------------
+
+After changing the microversion, you need to reset the local development environment.
+
+1. Delete the existing database file:
+
+.. code-block:: bash
+
+    rm -f ironic/ironic.sqlite
+
+2. Reinstall Ironic in the virtual environment:
+
+.. code-block:: bash
+
+    . .tox/local-ironic-dev/bin/activate
+    pip uninstall ironic
+    pip install -e .
+
+This change ensures that the APIs from the selected Ironic version
+will be applied, based on the release-to-microversion mapping in
+the Ironic codebase.