openedx-unsupported · timmc-edx · Sep 21, 2023 · Sep 21, 2023
diff --git a/docs/index.rst b/docs/index.rst
@@ -26,4 +26,5 @@ Contents
    pycharm_integration
    testing_and_debugging
    troubleshoot_general_tips
+   manual_upgrades
    advanced_configuration
diff --git a/docs/manual_upgrades.rst b/docs/manual_upgrades.rst
@@ -0,0 +1,16 @@
+Manual upgrade instructions
+###########################
+
+Occasionally there is a change to devstack that requires existing devstack installations to be manually upgraded. When this happens, instructions should be added here.
+
+Please add new instructions to the top, include a date, and make a post in the `Devstack forum <https://discuss.openedx.org/tags/c/development/11/devstack>`_.
+
+(If you just need to update your devstack to the latest version of everything, see :doc:`updating_devstack`.)
+
+2023-08-02 - Forum upgrade from Ruby 2 to 3
+*******************************************
+
+The forum service has been upgraded from Ruby 2 to Ruby 3. Developers who use forum will need to pull the new image and reprovision the service::
+
+    make dev.pull.forum  # pull in new forum image
+    make dev.provision.forum  # provision forum service
diff --git a/docs/troubleshoot_general_tips.rst b/docs/troubleshoot_general_tips.rst
@@ -302,6 +302,11 @@ Like with pulling images, you can also narrow these commands to specific service
 
 Running ``make dev.reset`` will do all the above for all services, which can be useful but takes much more time. It will also run a full ``docker system prune -f`` to get rid of unused images and networks.
 
+Manual Upgrades
+===============
+
+Sometimes there is a change to devstack that requires existing devstack installations to be manually upgraded. See :doc:`manual_upgrades` for recent cases of this.
+
 Starting From Scratch
 =====================