From 64f5697f5373c3904f62b39ac9c642b7c00b8e0e Mon Sep 17 00:00:00 2001
From: Chris Hegarty <62058229+ChrisHegarty@users.noreply.github.com>
Date: Mon, 9 Sep 2024 20:35:35 +0100
Subject: [PATCH] Add migration note about the deprecation of optional RegExp
 complement syntax (#13732)

This commit adds a migration note about the deprecation of optional RegExp complement support.
---
 lucene/MIGRATE.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/lucene/MIGRATE.md b/lucene/MIGRATE.md
index 79f756a2c1e..2f4728f5667 100644
--- a/lucene/MIGRATE.md
+++ b/lucene/MIGRATE.md
@@ -80,9 +80,22 @@ behaviour as 9.x, clone `PersianAnalyzer` in 9.x or create custom analyzer by us
 ### AutomatonQuery/CompiledAutomaton/RunAutomaton/RegExp no longer determinize (LUCENE-10010)
 
 These classes no longer take a `determinizeWorkLimit` and no longer determinize
-behind the scenes. It is the responsibility of the caller to to call
+behind the scenes. It is the responsibility of the caller to call
 `Operations.determinize()` for DFA execution.
 
+### RegExp optional complement syntax has been deprecated
+
+Support for the optional complement syntax (`~`) has been deprecated.
+The `COMPLEMENT` syntax flag has been removed and replaced by the
+`DEPRECATED_COMPLEMENT` flag. Users wanting to enable the deprecated
+complement support can do so by explicitly passing a syntax flags that
+has `DEPRECATED_COMPLEMENT` when creating a `RegExp`. For example:
+`new RegExp("~(foo)", RegExp.DEPRECATED_COMPLEMENT)`.
+
+Alternatively, and quite commonly, a more simple _complement bracket expression_,
+`[^...]`, may be a suitable replacement, For example, `[^fo]` matches any
+character that is not an `f` or `o`.
+
 ### DocValuesFieldExistsQuery, NormsFieldExistsQuery and KnnVectorFieldExistsQuery removed in favor of FieldExistsQuery (LUCENE-10436)
 
 These classes have been removed and consolidated into `FieldExistsQuery`. To migrate, caller simply replace those classes