Add section to Migration talking about typical areas that change between

major releases.

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 6252159025fd9fa8b21dbc97a9a4786ba8b248e3..4a6cad29153573d7d263fbb13ecf3d046c60b5ff 100644 (file)
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Backup and Restore
@@ -1909,13 +1909,6 @@ pg_dumpall -p 5432 | psql -d postgres -p 6543
    of downtime for an upgrade.
   
 
-  
-   In practice you probably want to test your client
-   applications on the new setup before switching over completely.
-   This is another reason for setting up concurrent installations
-   of old and new versions.
-  
-
   
    If you cannot or do not want to run two servers in parallel, you can
    do the backup step before installing the new version, bring down
@@ -1955,5 +1948,68 @@ psql -f backup postgres
     moving an installation like this will not work.)
    
   
+
+  
+   In practice you probably want to test your client applications on the
+   new version before switching over completely.  This is another reason
+   for setting up concurrent installations of old and new versions.  When
+   testing a PostgreSQL major upgrade, consider the
+   following categories of possible changes:
+  
+
+  
+
+   
+    Administration
+    
+     
+      The capabilities available for administrators to monitor and control
+      the server often change and improve in each major release.
+     
+    
+   
+
+   
+    SQL
+    
+     
+      Typically this includes new SQL command capabilities and not changes
+      in behavior, unless specifically mentioned in the release notes.
+     
+    
+   
+
+   
+    Library API
+    
+     
+      Typically libraries like libpq only add new
+      functionality, again unless mentioned in the release notes.
+     
+    
+   
+
+   
+    System Catalogs
+    
+     
+      System catalog changes usually only affect database management tools.
+     
+    
+   
+
+   
+    Server C-language API
+    
+     
+      This involved changes in the backend function API, which is written
+      in the C programming language.  Such changes effect code that
+      references backend functions deep inside the server.
+     
+    
+   
+
+  
+