DEV: Deprecate template overrides (#29544)

Template overrides have been advised against for a long time, and are increasingly hard to maintain as Discourse's development accelerates. This commit officially deprecates this customization method, which will be removed in the not-too-distant future (likely in the first half of 2025).

app/assets/javascripts/discourse-common/addon/lib/discourse-template-map.js

@@ -1,3 +1,5 @@
+import deprecated from "./deprecated";
+
 const pluginRegex = /^discourse\/plugins\/([^\/]+)\/(.*)$/;
 const themeRegex = /^discourse\/theme-([^\/]+)\/(.*)$/;
 
@@ -77,12 +79,28 @@ class DiscourseTemplateMap {
    * theme/plugin namespaces and overrides.
    */
   resolve(name) {
-    for (const cache of this.prioritizedCaches) {
+    const [themeMatch, pluginMatch, coreMatch] = this.prioritizedCaches.map(
+      (cache) => {
         const val = cache.get(name);
         if (val) {
           return val[val.length - 1];
         }
       }
+    );
+
+    if ((themeMatch || pluginMatch) && coreMatch) {
+      deprecated(
+        `[${
+          themeMatch || pluginMatch
+        }] Overriding templates is deprecated, and will soon be disabled. Use plugin outlets, CSS, or other customization APIs instead.`,
+        {
+          id: "discourse.resolver-template-overrides",
+          url: "https://meta.discourse.org/t/247487",
+        }
+      );
+    }
+
+    return themeMatch || pluginMatch || coreMatch;
   }
 
   /**

app/assets/javascripts/discourse/app/instance-initializers/component-templates.js

@@ -75,6 +75,14 @@ export default {
           console.error(message);
         }
       } else if (originalTemplate) {
+        deprecated(
+          `[${finalOverrideModuleName}] Overriding component templates is deprecated, and will soon be disabled. Use plugin outlets, CSS, or other customization APIs instead.`,
+          {
+            id: "discourse.component-template-overrides",
+            url: "https://meta.discourse.org/t/247487",
+          }
+        );
+
         const overrideTemplate = require(finalOverrideModuleName).default;
 
         COLOCATED_TEMPLATE_OVERRIDES.set(component, overrideTemplate);

app/assets/javascripts/discourse/tests/integration/component-templates-test.gjs

@@ -10,12 +10,16 @@ import { setupRenderingTest } from "discourse/tests/helpers/component-test";
 import { withSilencedDeprecationsAsync } from "discourse-common/lib/deprecated";
 import { registerTemporaryModule } from "../helpers/temporary-module-helper";
 
-function silenceMobileDeprecations(hooks) {
+function silenceMobileAndOverrideDeprecations(hooks) {
   let unsilenceCallback;
   hooks.beforeEach(() => {
     const promise = new Promise((resolve) => (unsilenceCallback = resolve));
     withSilencedDeprecationsAsync(
-      ["discourse.mobile-templates"],
+      [
+        "discourse.mobile-templates",
+        "discourse.resolver-template-overrides",
+        "discourse.component-template-overrides",
+      ],
       () => promise
     );
   });
@@ -112,7 +116,7 @@ function registerTemplateOnlyComponents() {
 }
 
 module("Integration | Initializers | plugin-component-templates", function (h) {
-  silenceMobileDeprecations(h);
+  silenceMobileAndOverrideDeprecations(h);
 
   module("template-only component definition behaviour", function (hooks) {
     hooks.beforeEach(() => registerTemplateOnlyComponents());

app/assets/javascripts/discourse/tests/unit/ember/resolver-test.js

@@ -295,20 +295,24 @@ module("Unit | Ember | resolver", function (hooks) {
     );
 
     // Defined in core and plugin
+    withSilencedDeprecations("discourse.resolver-template-overrides", () => {
       lookupTemplate(
         assert,
         "template:bar",
         "discourse/plugins/my-plugin/discourse/templates/bar",
         "prefers plugin version over core"
       );
+    });
 
     // Defined in core and plugin and theme
+    withSilencedDeprecations("discourse.resolver-template-overrides", () => {
       lookupTemplate(
         assert,
         "template:baz",
         "discourse/theme-12/discourse/templates/baz",
         "prefers theme version over plugin and core"
       );
+    });
 
     // Defined in core only
     lookupTemplate(
@@ -330,7 +334,9 @@ module("Unit | Ember | resolver", function (hooks) {
 
     setResolverOption("mobileView", true);
 
-    withSilencedDeprecations("discourse.mobile-templates", () => {
+    withSilencedDeprecations(
+      ["discourse.mobile-templates", "discourse.resolver-template-overrides"],
+      () => {
         // Default with plugin template override
         lookupTemplate(
           assert,
@@ -354,7 +360,8 @@ module("Unit | Ember | resolver", function (hooks) {
           "discourse/plugins/my-plugin/discourse/templates/mobile/baz",
           "preferring plugin mobile version over non-plugin mobile version"
         );
-    });
+      }
+    );
   });
 
   test("resolves templates with 'admin' prefix", function (assert) {