diff --git a/ChangeLog b/ChangeLog
index 3d2ceaa67..a9a52c6dc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2007-06-08  Elijah Newren  <newren gmail com>
+
+	* src/metacity.schemas.in:
+	Update the raise_on_click description to try to prevent misuses,
+	to appropriately warn users, and to stop wasting the time of
+	application developers.  #445447, #389923
+
 2007-06-06  Thomas Thurman  <thomas@thurman.org.uk>
 
 	* frames.c, core.[ch]: changed all tabs to spaces.
diff --git a/src/metacity.schemas.in b/src/metacity.schemas.in
index 05c24bcac..5929342f4 100644
--- a/src/metacity.schemas.in
+++ b/src/metacity.schemas.in
@@ -93,14 +93,29 @@
          <short>Whether raising should be a side-effect of other user
                 interactions</short>
          <long>
+           Setting this option to false can lead to buggy behavior, so
+           users are strongly discouraged from changing it from the default
+           of true.
+
            Many actions (e.g. clicking in the client area, moving or
            resizing the window) normally raise the window as a
            side-effect. Set this option to false to decouple raising from
            other user actions.  Even when this option is false, windows can
            still be raised by an alt-left-click anywhere on the window, a
-           normal click on the window decorations, or by special messages,
-           such as activation requests from pagers. This option is
-           currently disabled in click-to-focus mode.
+           normal click on the window decorations, or by special messages
+           from pagers, such as activation requests from tasklist applets.
+           This option is currently disabled in click-to-focus mode.
+
+           Note that the list of ways to raise windows when raise_on_click
+           is false does not include programmatic requests from
+           applications to raise windows; such requests will be ignored
+           regardless of the reason for the request.  If you are an
+           application developer and have a user complaining that your
+           application does not work with this setting disabled, tell them
+           it is _their_ fault for breaking their window manager and that
+           they need to change this option back to true or live with the
+           bug they requested.  See also
+           http://bugzilla.gnome.org/show_bug.cgi?id=445447#c6.
          </long>
       </locale>
     </schema>