firefox: default configPath to XDG on 26.05

Use `lib.hm.deprecations.mkStateVersionOptionDefault` to keep the legacy `.mozilla/firefox` default for existing configurations while switching new Linux configurations to `"${config.xdg.configHome}/mozilla/firefox"`.

Add focused tests for the legacy and XDG defaults plus a news entry describing the transition.

Closes #8200.
Supersedes #8716 and the earlier attempt in #8672.

Co-authored-by: Heitor <44377258+HeitorAugustoLN@users.noreply.github.com>

docs/release-notes/rl-2605.md

@@ -53,3 +53,7 @@ changes are only active if the `home.stateVersion` option is set to
 
 - The options [](#opt-programs.neovim.withPython3) and
   [](#opt-programs.neovim.withRuby) now default to `false` following nixpkgs
+
+- On Linux, `programs.firefox.configPath` now defaults to
+  `"${config.xdg.configHome}/mozilla/firefox"` for `home.stateVersion = "26.05"` and later.
+  Older state versions keep the legacy default of `".mozilla/firefox"`.

modules/programs/firefox/default.nix

@@ -1,9 +1,44 @@
-{ lib, config, ... }:
+{
+  lib,
+  config,
+  pkgs,
+  options,
+  ...
+}:
 let
   inherit (lib) mkRemovedOptionModule;
 
   cfg = config.programs.firefox;
 
+  linuxConfigHome = lib.removePrefix "${config.home.homeDirectory}/" config.xdg.configHome;
+
+  linuxConfigPathStateVersion = lib.hm.deprecations.mkStateVersionOptionDefault {
+    inherit (config.home) stateVersion;
+    since = "26.05";
+    inherit config;
+    inherit options;
+    deferWarningToConfig = true;
+    optionPath = [
+      "programs"
+      "firefox"
+      "configPath"
+    ];
+    legacy = {
+      value = ".mozilla/firefox";
+    };
+    current = {
+      value = "${linuxConfigHome}/mozilla/firefox";
+      text = ''"''${config.xdg.configHome}/mozilla/firefox"'';
+    };
+    shouldWarn =
+      { optionUsesDefaultPriority, ... }: optionUsesDefaultPriority && !pkgs.stdenv.hostPlatform.isDarwin;
+    extraWarning = ''
+      To migrate to the XDG path, move `~/.mozilla/firefox` to
+      `$XDG_CONFIG_HOME/mozilla/firefox` and remove the old directory.
+      Native messaging hosts are not moved by this option change.
+    '';
+  };
+
   modulePath = [
     "programs"
     "firefox"
@@ -28,7 +63,7 @@ in
       unwrappedPackageName = "firefox-unwrapped";
 
       platforms.linux = {
-        configPath = ".mozilla/firefox";
+        configPath = linuxConfigPathStateVersion.default;
       };
       platforms.darwin = {
         configPath = "Library/Application Support/Firefox";
@@ -56,6 +91,8 @@ in
   ];
 
   config = lib.mkIf cfg.enable {
+    warnings = lib.optional linuxConfigPathStateVersion.shouldWarn linuxConfigPathStateVersion.warning;
+
     mozilla.firefoxNativeMessagingHosts =
       cfg.nativeMessagingHosts
       # package configured native messaging hosts (entire browser actually)

tests/modules/programs/firefox/config-path-warning.nix

@@ -0,0 +1,48 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  firefoxMockOverlay = import ./setup-firefox-mock-overlay.nix [
+    "programs"
+    "firefox"
+  ];
+in
+{
+  imports = [ firefoxMockOverlay ];
+
+  config = lib.mkIf (config.test.enableBig && !pkgs.stdenv.hostPlatform.isDarwin) {
+    home.stateVersion = "25.11";
+
+    programs.firefox = {
+      enable = true;
+      profiles.test.settings."general.smoothScroll" = false;
+    };
+
+    nmt.script = ''
+      assertFileRegex \
+        home-files/.mozilla/firefox/test/user.js \
+        'user_pref\("general\.smoothScroll", false\);'
+
+      assertPathNotExists \
+        home-files/.config/mozilla/firefox/test/user.js
+    '';
+
+    test.asserts.warnings.expected = [
+      ''
+        The default value of `programs.firefox.configPath` has changed from `".mozilla/firefox"` to `"/home/hm-user/.config/mozilla/firefox"`.
+        You are currently using the legacy default (`".mozilla/firefox"`) because `home.stateVersion` is less than "26.05".
+        To silence this warning and keep legacy behavior, set:
+        programs.firefox.configPath = ".mozilla/firefox";
+        To adopt the new default behavior, set:
+          programs.firefox.configPath = "/home/hm-user/.config/mozilla/firefox";
+
+        To migrate to the XDG path, move `~/.mozilla/firefox` to
+        `$XDG_CONFIG_HOME/mozilla/firefox` and remove the old directory.
+        Native messaging hosts are not moved by this option change.
+      ''
+    ];
+  };
+}

tests/modules/programs/firefox/config-path-xdg-default.nix

@@ -0,0 +1,34 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  firefoxMockOverlay = import ./setup-firefox-mock-overlay.nix [
+    "programs"
+    "firefox"
+  ];
+in
+{
+  imports = [ firefoxMockOverlay ];
+
+  config = lib.mkIf (config.test.enableBig && !pkgs.stdenv.hostPlatform.isDarwin) {
+    home.stateVersion = "26.05";
+    xdg.configHome = "/home/hm-user/.config-custom";
+
+    programs.firefox = {
+      enable = true;
+      profiles.test.settings."general.smoothScroll" = false;
+    };
+
+    nmt.script = ''
+      assertFileRegex \
+        home-files/.config-custom/mozilla/firefox/test/user.js \
+        'user_pref\("general\.smoothScroll", false\);'
+
+      assertPathNotExists \
+        home-files/.mozilla/firefox/test/user.js
+    '';
+  };
+}

tests/modules/programs/firefox/default.nix

@@ -1,4 +1,6 @@
 {
+  "firefox-config-path-xdg-default" = ./config-path-xdg-default.nix;
+  "firefox-config-path-warning" = ./config-path-warning.nix;
   "firefox-multiple-derivatives" = ./multiple-derivatives.nix;
 }
 // (import ./firefox.nix)

tests/modules/programs/firefox/final-package.nix

@@ -2,6 +2,7 @@ modulePath:
 {
   config,
   lib,
+  pkgs,
   realPkgs,
   ...
 }:
@@ -12,7 +13,14 @@ let
 
 in
 lib.mkIf config.test.enableBig (
-  lib.setAttrByPath modulePath { enable = true; }
+  lib.setAttrByPath modulePath (
+    {
+      enable = true;
+    }
+    // lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux {
+      configPath = ".mozilla/firefox";
+    }
+  )
   // {
     home.stateVersion = "19.09";
 

tests/modules/programs/firefox/policies.nix

@@ -21,6 +21,7 @@ in
     }
     // lib.setAttrByPath modulePath {
       enable = true;
+      configPath = lib.mkIf pkgs.stdenv.hostPlatform.isLinux ".mozilla/firefox";
       policies = {
         BlockAboutConfig = true;
       };

tests/modules/programs/firefox/profiles/bookmarks/default.nix

@@ -24,6 +24,7 @@ in
     }
     // lib.setAttrByPath modulePath {
       enable = true;
+      configPath = lib.mkIf pkgs.stdenv.hostPlatform.isLinux ".mozilla/firefox";
       profiles.bookmarks = {
         settings = {
           "general.smoothScroll" = false;

tests/modules/programs/firefox/state-version-19_09.nix

@@ -17,7 +17,10 @@ in
     {
       home.stateVersion = "19.09";
     }
-    // lib.setAttrByPath modulePath { enable = true; }
+    // lib.setAttrByPath modulePath {
+      enable = true;
+      configPath = ".mozilla/firefox";
+    }
     // {
       nmt.script = ''
         assertFileRegex \

tests/modules/programs/thunderbird/thunderbird-with-firefox.nix

@@ -8,6 +8,7 @@
 lib.recursiveUpdate (import ./thunderbird.nix { inherit config lib pkgs; }) {
   programs.firefox = {
     enable = true;
+    configPath = lib.mkIf pkgs.stdenv.hostPlatform.isLinux ".mozilla/firefox";
     package = null;
   };
 }