From 0cfa52d292174a287202366e9e82e7cb7922fe63 Mon Sep 17 00:00:00 2001
From: Jeff Ohrstrom <johrstrom@osc.edu>
Date: Wed, 7 Feb 2024 10:07:16 -0500
Subject: [PATCH] add a note about this chagne to the RNs (#929)

---
 source/reference/files/ondemand-d-ymls.rst  | 13 +++++++------
 source/release-notes/v3.1-release-notes.rst | 20 ++++++++++++++++++++
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/source/reference/files/ondemand-d-ymls.rst b/source/reference/files/ondemand-d-ymls.rst
index 71b0a54f..f3da82c5 100644
--- a/source/reference/files/ondemand-d-ymls.rst
+++ b/source/reference/files/ondemand-d-ymls.rst
@@ -637,25 +637,26 @@ Configuration Properties
 
       module_file_dir: "/etc/reporting/modules"
 
+.. _user_settings_file:
 .. describe:: user_settings_file (String, '.ood')
 
-  The name of the file to store user settings. This file is used to store the selected profile.
-  The path to the file is managed by the configuration variable ``Configuration.dataroot``.
-  This is usually: ``~/ondemand/data/sys/dashboard``
+  The full path of the file to store user settings. This file is used to store
+  any user defined settings.
 
   Default
     A file called '.ood'.
 
     .. code-block:: yaml
 
-      user_settings_file: ".ood"
+      user_settings_file: "~/.config/ondemand/settings.yml"
 
   Example
-    Use ``user_settings.txt`` as the file name for user settings.
+    Use ``user_settings.txt`` as the file name for user settings
+    and change the path slightly.
 
     .. code-block:: yaml
 
-      user_settings_file: "user_settings.txt"
+      user_settings_file: "~/.config/local/open-ondemand/user_settings.txt"
 
 .. describe:: facl_domain (String, null)
 
diff --git a/source/release-notes/v3.1-release-notes.rst b/source/release-notes/v3.1-release-notes.rst
index 9ebf71ef..d7db5330 100644
--- a/source/release-notes/v3.1-release-notes.rst
+++ b/source/release-notes/v3.1-release-notes.rst
@@ -6,6 +6,7 @@ v3.1 Release Notes
 Administrative changes
 ----------------------
 
+- `Breaking Changes`_
 - `Deprecations`_
 - `Dependency updates`_
 - `Upgrade directions`_
@@ -27,6 +28,25 @@ New Features
 Details of administrative changes
 ---------------------------------
 
+Breaking Changes
+................
+
+User Settings File Change
+*************************
+
+We had to change the location of the :ref:`user settings file <user_settings_file>`
+off of the ``DATAROOT`` which is cluster specific and problematic for sites that
+have separate HOME directories for each cluster.
+
+The new default location is under the ``XDG_CONFIG_HOME``. This change was made
+to accomidate sites that have separate HOME directories for each cluster.
+
+Sites who have never used this configuration do not need to do anything.
+
+Sites that have reconfigured the :ref:`user settings file <user_settings_file>`
+need to provide the full path for this file.  It's recommended that you do not
+use a path in the ``DATAROOT`` as that is cluster specific.
+
 Deprecations
 ............