diff --git a/doc/xml/release.xml b/doc/xml/release.xml
index 4a4139230..edc1b988a 100644
--- a/doc/xml/release.xml
+++ b/doc/xml/release.xml
@@ -35,6 +35,18 @@
 
             <release-doc-list>
                 <release-improvement-list>
+                    <release-item>
+                        <github-issue id="1774"/>
+                        <github-pull-request id="1993"/>
+
+                        <release-item-contributor-list>
+                            <release-item-contributor id="christophe.courtois"/>
+                            <release-item-reviewer id="david.steele"/>
+                        </release-item-contributor-list>
+
+                        <p>Add explicit instructions for upgrading between <id>2.x</id> versions.</p>
+                    </release-item>
+
                     <release-item>
                         <release-item-contributor-list>
                             <release-item-contributor id="david.steele"/>
diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml
index 4c645066b..a511de908 100644
--- a/doc/xml/user-guide.xml
+++ b/doc/xml/user-guide.xml
@@ -866,6 +866,13 @@
 
             <p><postgres/> and repository options must be indexed when using the new names introduced in <proper>v2</proper>, e.g. <br-option>pg1-host</br-option>, <br-option>pg1-path</br-option>, <br-option>repo1-path</br-option>, <br-option>repo1-type</br-option>, etc.</p>
         </section>
+
+        <!-- =================================================================================================================== -->
+        <section id="v2.x">
+            <title>Upgrading {[project]} from v2.x to v2.y</title>
+
+            <p>Upgrading from <proper>v2.x</proper> to <proper>v2.y</proper> is straight-forward. The repository format has not changed, so for most installations it is simply a matter of installing binaries for the new version. It is also possible to downgrade if you have not used new features that are unsupported by the older version.</p>
+        </section>
     </section>
 
     <!-- ======================================================================================================================= -->