From c6a68a171a299f39a3bd577b085a38f65c7569ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Fri, 5 May 2023 09:08:02 +0200
Subject: Add uppcoming incompatibility note about matching +0.0 and -0.0

---
 .../general_info/upcoming_incompatibilities.xml    | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/system/doc/general_info/upcoming_incompatibilities.xml b/system/doc/general_info/upcoming_incompatibilities.xml
index 04ab4459c0..4d31784f8d 100644
--- a/system/doc/general_info/upcoming_incompatibilities.xml
+++ b/system/doc/general_info/upcoming_incompatibilities.xml
@@ -53,6 +53,7 @@
     </section>
 
     <section>
+      <marker id="maybe_expr"/>
       <title>Feature maybe_expr will be enabled by default</title>
       <p>
 	As of OTP 27, the <c>maybe_expr</c> feature will be approved
@@ -119,6 +120,41 @@
         the regular expression before matching with it.</p></item>
       </list>
     </section>
+
+    <section>
+      <marker id="float_matching"/>
+      <title>0.0 and -0.0 will no longer be exactly equal</title>
+
+      <p>Currently, the floating point numbers <c>0.0</c> and <c>-0.0</c>
+      have distinct internal representations. That can be seen if they are
+      converted to binaries:</p>
+      <pre>
+1&gt; <input>&lt;&lt;0.0/float&gt;&gt;.</input>
+&lt;&lt;0,0,0,0,0,0,0,0&gt;&gt;
+2&gt; <input>&lt;&lt;-0.0/float&gt;>.</input>
+&lt;&lt;128,0,0,0,0,0,0,0>></pre>
+
+      <p>However, when they are matched against each other or compared
+      using the <c>=:=</c> operator, they are considered to be
+      equal. Thus, <c>0.0 =:= -0.0</c> currently returns
+      <c>true</c>.</p>
+
+      <p>In Erlang/OTP 27, <c>0.0 =:= -0.0</c> will return <c>false</c>, and matching
+      <c>0.0</c> against <c>-0.0</c> will fail. When used as map keys, <c>0.0</c> and
+      <c>-0.0</c> will be considered to be distinct.</p>
+
+      <p>The <c>==</c> operator will continue to return <c>true</c>
+      for <c>0.0 == -0.0</c>.</p>
+
+      <p>To help to find code that might need to be revised, in OTP 27
+      there will be a new compiler warning when matching against
+      <c>0.0</c> or comparing to that value using the <c>=:=</c>
+      operator. The warning can be suppressed by matching against
+      <c>+0.0</c> instead of <c>0.0</c>.</p>
+
+      <p>We plan to introduce the same warning in OTP 26.1, but by default it
+      will be disabled.</p>
+    </section>
   </section>
 
   <section>
-- 
cgit v1.2.1