diff --git a/CHANGELOG.md b/CHANGELOG.md
index a5ff074c..3e8628cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Read environment variables from `/etc/default/warewulfd` #725
 - Add support for VLANs to NetworkManager, wicked, ifcfg, debian.network_interfaces overlays. #1257
 - Add support for static routes to NetworkManager, wicked, ifcfg, debian.network_interfaces overlays. #1257
+- Add `wwctl upgrade <config|nodes>`. #230, #517
 
 ### Changed
 
diff --git a/userdocs/contents/configuration.rst b/userdocs/contents/configuration.rst
index 9c0bee4b..13309244 100644
--- a/userdocs/contents/configuration.rst
+++ b/userdocs/contents/configuration.rst
@@ -201,6 +201,26 @@ command.
    This also goes for ``warewulf.conf`` as well - any changes made also require ``warewulfd`` to be restarted.
    The restart should be done using the following command: ``systemctl restart warewulfd``
 
+Upgrades
+========
+
+New versions of Warewulf might introduce changes to ``warewulf.conf`` and ``nodes.conf``.
+The ``wwctl upgrade`` command can help ease the transition between versions.
+
+.. note::
+
+   ``wwctl upgrade`` will back up any files before it changes them (to ``<name>-old``)
+   but it is good practice to back up your configuration manually.
+
+.. code-block:: console
+
+   # wwctl upgrade config
+   # wwctl upgrade nodes --add-defaults --replace-overlays
+
+Both upgrade commands support specifying ``--output-path=-``
+to print the upgraded configuration file to standard out
+for inspection before replacing the configuration files.
+
 Directories
 ===========