Help: Add 3.1 release note about '#' escaping in Makefiles (#15322)

The change in commit v3.1.0-rc1~174^2 (Makefile: Handle '#' in
COMPILE_OPTIONS, 2014-08-12) was not compatible with code that
tries to workaround the original bug.  Unfortunately there is no
good way to fix the bug in a compatible way.  Add a release note
to call attention to the change.

1 files changed, 22 insertions, 0 deletions

diff --git a/Help/release/3.1.0.rst b/Help/release/3.1.0.rst
index a5b3e8e..97a63f9 100644
--- a/Help/release/3.1.0.rst
+++ b/Help/release/3.1.0.rst
@@ -353,6 +353,28 @@ Deprecated and Removed Features
 
   CMake 3.1 again requires the quotes for this to work correctly.
 
+* Prior to CMake 3.1 the Makefile generators did not escape ``#``
+  correctly inside make variable assignments used in generated
+  makefiles, causing them to be treated as comments.  This made
+  code like::
+
+    add_compile_options(-Wno-#pragma-messages)
+
+  not work in Makefile generators, but work in other generators.
+  Now it is escaped correctly, making the behavior consistent
+  across generators.  However, some projects may have tried to
+  workaround the original bug with code like::
+
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-\\#pragma-messages")
+
+  This added the needed escape for Makefile generators but also
+  caused other generators to pass ``-Wno-\#pragma-messages`` to
+  the shell, which would work only in POSIX shells.
+  Unfortunately the escaping fix could not be made in a compatible
+  way so this platform- and generator-specific workaround no
+  longer works.  Project code may test the :variable:`CMAKE_VERSION`
+  variable value to make the workaround version-specific too.
+
 * Callbacks established by the :command:`variable_watch` command will no
   longer receive the ``ALLOWED_UNKNOWN_READ_ACCESS`` access type when
   the undocumented ``CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS`` variable is