From 0ef3d797ebf4a7a52dab055292a2a639d109fdf6 Mon Sep 17 00:00:00 2001
From: Hubert Olender <olender.hub@gmail.com>
Date: Thu, 4 Jun 2026 18:06:19 +0200
Subject: [PATCH 1/4] docs(ember): add deprecation guide for Comparable mixin

Add migration guide for the Comparable mixin deprecation in Ember v6, showing how to replace mixin usage with a direct compare() method.
---
 .../ember/v6/deprecate-comparable-mixin.md    | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 content/ember/v6/deprecate-comparable-mixin.md

diff --git a/content/ember/v6/deprecate-comparable-mixin.md b/content/ember/v6/deprecate-comparable-mixin.md
new file mode 100644
index 00000000..be091fcf
--- /dev/null
+++ b/content/ember/v6/deprecate-comparable-mixin.md
@@ -0,0 +1,37 @@
+---
+title: Deprecate Comparable mixin
+id: deprecate-comparable-mixin
+until: 8.0.0
+since: 7.2.0
+---
+
+The `Comparable` mixin is deprecated.
+
+Apps and addons should stop importing or extending `Comparable`. To provide custom comparison behavior, define a function-valued `compare(other)` method directly on the object or class instead.
+
+Before:
+
+```js
+import EmberObject from '@ember/object';
+import Comparable from '@ember/-internals/runtime/lib/mixins/comparable';
+
+const Rectangle = EmberObject.extend(Comparable, {
+  compare(other) {
+    // custom comparison logic
+  },
+});
+```
+
+After:
+
+```js
+import EmberObject from '@ember/object';
+
+const Rectangle = EmberObject.extend({
+  compare(other) {
+    // custom comparison logic
+  },
+});
+```
+
+Defining `compare(other)` directly is sufficient. Ember's `compare()` function uses duck-typing and will call a function-valued `compare` method when one is present, so the `Comparable` mixin is no longer required.

From 9880088922307a2d5f2c91910a7320bf92db3cee Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Mon, 31 Aug 2026 19:26:40 -0400
Subject: [PATCH 2/4] Update comparable deprecation guide

---
 .../ember/{v6 => v7}/deprecate-comparable-mixin.md   | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
 rename content/ember/{v6 => v7}/deprecate-comparable-mixin.md (65%)

diff --git a/content/ember/v6/deprecate-comparable-mixin.md b/content/ember/v7/deprecate-comparable-mixin.md
similarity index 65%
rename from content/ember/v6/deprecate-comparable-mixin.md
rename to content/ember/v7/deprecate-comparable-mixin.md
index be091fcf..a09d4254 100644
--- a/content/ember/v6/deprecate-comparable-mixin.md
+++ b/content/ember/v7/deprecate-comparable-mixin.md
@@ -1,6 +1,5 @@
 ---
 title: Deprecate Comparable mixin
-id: deprecate-comparable-mixin
 until: 8.0.0
 since: 7.2.0
 ---
@@ -25,13 +24,14 @@ const Rectangle = EmberObject.extend(Comparable, {
 After:
 
 ```js
-import EmberObject from '@ember/object';
-
-const Rectangle = EmberObject.extend({
+class Rectangle {
+  // Returns -1, 0, 1
   compare(other) {
     // custom comparison logic
   },
-});
+}
 ```
 
-Defining `compare(other)` directly is sufficient. Ember's `compare()` function uses duck-typing and will call a function-valued `compare` method when one is present, so the `Comparable` mixin is no longer required.
+Defining `compare(other)` directly is sufficient. 
+
+However, if you need to `sort` a list of your objects, you will want to define a separate [`comparator function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description).

From 8e260289c2caf40c7da6f62d42aa7e39c8d2a315 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Tue, 1 Sep 2026 11:46:15 -0400
Subject: [PATCH 3/4] Update content/ember/v7/deprecate-comparable-mixin.md

Co-authored-by: Katie Gengler <katie@kmg.io>
---
 content/ember/v7/deprecate-comparable-mixin.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/ember/v7/deprecate-comparable-mixin.md b/content/ember/v7/deprecate-comparable-mixin.md
index a09d4254..e09d8584 100644
--- a/content/ember/v7/deprecate-comparable-mixin.md
+++ b/content/ember/v7/deprecate-comparable-mixin.md
@@ -4,7 +4,7 @@ until: 8.0.0
 since: 7.2.0
 ---
 
-The `Comparable` mixin is deprecated.
+The `Comparable` mixin is deprecated. This mixin was private but as it may have been intimate API, per our policy we've added a deprecation that will remain for at least one LTS. 
 
 Apps and addons should stop importing or extending `Comparable`. To provide custom comparison behavior, define a function-valued `compare(other)` method directly on the object or class instead.
 

From dba6bcd4d5b0685aea29ae54ee90710eee480a31 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Tue, 1 Sep 2026 11:48:33 -0400
Subject: [PATCH 4/4] Update deprecation version for Comparable mixin

---
 content/ember/v7/deprecate-comparable-mixin.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/ember/v7/deprecate-comparable-mixin.md b/content/ember/v7/deprecate-comparable-mixin.md
index e09d8584..3ef26b56 100644
--- a/content/ember/v7/deprecate-comparable-mixin.md
+++ b/content/ember/v7/deprecate-comparable-mixin.md
@@ -1,6 +1,6 @@
 ---
 title: Deprecate Comparable mixin
-until: 8.0.0
+until: 7.5.0
 since: 7.2.0
 ---