Add a "Potentially Breaking Changes" section to the Clang release notes

[aaron.ballman]

Summary

Sometimes we make changes to the compiler that we expect may cause disruption for users. For example, we may strengthen a warning to default to be an error, or fix an accepts-invalid bug that's been around for a long time, etc which may cause previously accepted code to now be rejected. Rather than hope users discover that information by reading all of the release notes, it's better that we call these out in one location at the top of the release notes.

Based on feedback collected in the discussion at:
https://discourse.llvm.org/t/configure-script-breakage-with-the-new-werror-implicit-function-declaration/65213/

[aaron.ballman]

@tstellar or @thieta -- will this cause any problems for your release scripts? (Note I used Clang |release| in the new wording; I can pull the |release| bit out if that's a problem.) Also, do you suppose there's a way we can flag specific release notes as being "critical" so that the script automatically adds information to a more public download page such as: https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.0 ?

[mgorny]

I think this is a good idea — thanks for doing this.

[thesamesam]

Thanks!

[tschuett]

The LLD release notes always refer to the Diff where the change was introduced. It is kind of sad that we loose all the discussions when we move to GitHub PRs.

[sylvestre.ledru]

clang/docs/ReleaseNotes.rst

49

[MaskRay]

clang/docs/ReleaseNotes.rst

49

Two backsticks for rst :)

[thesamesam]

clang/docs/ReleaseNotes.rst

52

Reflecting on this a bit, do wonder about explicitly calling out configure scripts, as I suspect it's something a lot of people may not even think of.

"The LLVM team recommends that projects using configure scripts verify the results do not change before/after setting -Werror=implicit-function-declarations (repeat for others) to avoid incompatibility with Clang 16."

[aaron.ballman]

clang/docs/ReleaseNotes.rst

52

Good idea!

clang/docs/ReleaseNotes.rst

 latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or the
 `LLVM Web Site <https://llvm.org>`_.
 
 Note that if you are reading this file from a Git checkout or the
 main Clang web page, this document applies to the *next* release, not
 the current one. To see the release notes for a specific release, please
 see the `releases page <https://llvm.org/releases/>`_.
 
+Potentially Breaking Changes
+============================
+These changes are ones which we think may surprise users when upgrading to
+Clang |release| because of the opportunity they pose for disruption to existing
+code bases.
+
+- Clang will now correctly diagnose as ill-formed a constant expression where an
+  enum without a fixed underlying type is set to a value outside the range of
+  the enumeration's values. Due to the extended period of time this bug was
+  present in major C++ implementations (including Clang), this error has the
+  ability to be downgraded into a warning (via:
+  ``-Wno-error=enum-constexpr-conversion``) to provide a transition period for
+  users. This diagnostic is expected to turn into an error-only diagnostic in
+  the next Clang release. Fixes
+  `Issue 50055: <https://github.com/llvm/llvm-project/issues/50055>`_.
+- ``-Wincompatible-function-pointer-types`` now defaults to an error in all C
+  language modes. It may be downgraded to a warning with
+  ``-Wno-error=incompatible-function-pointer-types`` or disabled entirely with
+  ``-Wno-implicit-function-pointer-types``. *NOTE* We recommend that projects
+  using configure scripts verify the results do not change before/after setting
+  ``-Werror=incompatible-function-pointer-types`` to avoid incompatibility with
+  Clang 16.
+
+
 What's New in Clang |release|?
 ==============================
 
 Some of the major new features and improvements to Clang are listed
 here. Generic improvements to Clang as a whole or to its underlying
 infrastructure are described first, followed by language-specific
 sections with improvements to Clang's support for those languages.
 

 - Fix ``__builtin_assume_aligned`` crash when the 1st arg is array type. This fixes
   `Issue 57169 <https://github.com/llvm/llvm-project/issues/57169>`_
 - Clang configuration files are now read through the virtual file system
   rather than the physical one, if these are different.
 
 
 Improvements to Clang's diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- Clang will now correctly diagnose as ill-formed a constant expression where an
-  enum without a fixed underlying type is set to a value outside the range of
-  the enumeration's values. Due to the extended period of time this bug was
-  present in major C++ implementations (including Clang), this error has the
-  ability to be downgraded into a warning (via: -Wno-error=enum-constexpr-conversion)
-  to provide a transition period for users. This diagnostic is expected to turn
-  into an error-only diagnostic in the next Clang release. Fixes
-  `Issue 50055: <https://github.com/llvm/llvm-project/issues/50055>`_.
 - Clang will now check compile-time determinable string literals as format strings.
   Fixes `Issue 55805: <https://github.com/llvm/llvm-project/issues/55805>`_.
 - ``-Wformat`` now recognizes ``%b`` for the ``printf``/``scanf`` family of
   functions and ``%B`` for the ``printf`` family of functions. Fixes
   `Issue 56885: <https://github.com/llvm/llvm-project/issues/56885>`_.
 - Introduced ``-Wsingle-bit-bitfield-constant-conversion``, grouped under
   ``-Wbitfield-constant-conversion``, which diagnoses implicit truncation when
   ``1`` is assigned to a 1-bit signed integer bitfield. This fixes
   `Issue 53253 <https://github.com/llvm/llvm-project/issues/53253>`_. To reduce
   potential false positives, this diagnostic will not diagnose use of the
   ``true`` macro (from ``<stdbool.h>>`) in C language mode despite the macro
   being defined to expand to ``1``.
-- ``-Wincompatible-function-pointer-types`` now defaults to an error in all C
-  language modes. It may be downgraded to a warning with
-  ``-Wno-error=incompatible-function-pointer-types`` or disabled entirely with
-  ``-Wno-implicit-function-pointer-types``.
 - Clang will now print more information about failed static assertions. In
   particular, simple static assertion expressions are evaluated to their
   compile-time value and printed out if the assertion fails.
 - Diagnostics about uninitialized ``constexpr`` varaibles have been improved
   to mention the missing constant initializer.
 - Correctly diagnose a future keyword if it exist as a keyword in the higher
   language version and specifies in which version it will be a keyword. This
   supports both c and c++ language.