[clang] [Docs] Add release note about Clang-defined target OS macros (PR #79879)

[Zixu Wang via cfe-commits]

https://github.com/zixu-w created https://github.com/llvm/llvm-project/pull/79879

None

>From b773a6911ef1f842b7d5d548c98109012d80dd10 Mon Sep 17 00:00:00 2001
From: Zixu Wang <zixu_wang at apple.com>
Date: Thu, 25 Jan 2024 16:35:37 -0800
Subject: [PATCH] [Docs] Add release note about Clang-defined target OS macros

---
 clang/docs/ReleaseNotes.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 05c42f8485d4ee3..29377f9537e88f7 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -49,6 +49,24 @@ ABI Changes in This Version
 AST Dumping Potentially Breaking Changes
 ----------------------------------------
 
+Clang Frontend Potentially Breaking Changes
+-------------------------------------------
+
+Target OS macros extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new Clang extension (see :ref:`here <target_os_detail>`) is enabled for
+Darwin (Apple platform) targets. Clang now defines ``TARGET_OS_*`` macros for
+these targets, which could break existing code bases with improper checks for
+the ``TARGET_OS_`` macros. For example, existing checks might fail to include
+the ``TargetConditionals.h`` header from Apple SDKs and therefore leaving the
+macros undefined and guarded code unexercised.
+
+Affected code should be checked to see if it's still intended for the specific
+target and fixed accordingly.
+
+The extension can be turned off by the option ``-fno-define-target-os-macros``
+as a workaround.
+
 What's New in Clang |release|?
 ==============================
 Some of the major new features and improvements to Clang are listed
@@ -83,6 +101,17 @@ Non-comprehensive list of changes in this release
 New Compiler Flags
 ------------------
 
+.. _target_os_detail:
+
+Target OS macros extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+A pair of new flags ``-fdefine-target-os-macros`` and
+``-fno-define-target-os-macros`` has been added to Clang to enable/disable the
+extension to provide built-in definitions of a list of ``TARGET_OS_*`` macros
+based on the target triple.
+
+The extension is enabled by default for Darwin (Apple platform) targets.
+
 Deprecated Compiler Flags
 -------------------------