diff --git a/Shorewall/changelog.txt b/Shorewall/changelog.txt
index f21f39ed9..4a4dd15e6 100755
--- a/Shorewall/changelog.txt
+++ b/Shorewall/changelog.txt
@@ -10,6 +10,8 @@ Changes in 3.0.3
 
 5) Fix help text for restore. Add -q to help for safe-start and safe-restart.
 
+6) Add more migration information to release notes.
+
 Changes in 3.0.2
 
 1) Typos in the Samples corrected.
diff --git a/Shorewall/releasenotes.txt b/Shorewall/releasenotes.txt
index f049122cb..2ef8fef2d 100755
--- a/Shorewall/releasenotes.txt
+++ b/Shorewall/releasenotes.txt
@@ -1,5 +1,40 @@
 Shorewall 3.0.3
 
+Note to users upgrading from Shorewall 2.x
+
+   Most problems associated with upgrades come from two causes:
+
+   - The user didn't read and follow the migration considerations in these
+     release notes.
+
+   - The user mis-handled the /etc/shorewall/shorewall.conf file during
+     upgrade. Shorewall is designed to allow the default behavior of
+     the product to evolve over time. To make this possible, the design
+     assumes that you will not replace your current shorewall.conf file
+     during upgrades. If you feel absolutely compelled to have the latest
+     comments and options in your shorewall.conf then you must proceed
+     carefully.
+
+     The new/changed options in shorewall 3.0 are listed below. If you don't
+     want to convert to the new 3.0 format for /etc/shorewall/zones and you
+     don't want to replace your current rules that use 2.x builtin actions,
+     then if you plan to use the 3.0 shorewall.conf file then you must change
+     it as follows:
+
+     - SPECFILE  The 3.0 shorewall.conf file has IPSECFILE=zones. You want to
+                 set it to IPSECFILE=ipsec. This will indicate that your
+                 /etc/shorewall/zones file is in the pre-3.0 format.
+
+     - FW        The 3.0 shorewall.conf file has FW undefined. If you have
+                 named your firewall zone something other than 'fw' then you
+                 must set FW accordingly.
+
+     - MAPOLDACTIONS
+
+                 The 3.0 shorewall.conf file has MAPOLDACTIONS=No. You want to
+                 set it to MAPOLDACTIONS=Yes in order to permit rules that use
+                 the 2.x builtin actions such as AllowPing to continue to work.
+
 Problems Corrected in 3.0.3
 
 1) The comments in the /etc/shorewall/shorewall.conf and