From f43847516d37bac039f34473b203325743318c8e Mon Sep 17 00:00:00 2001
From: JBYoshi <12983479+JBYoshi@users.noreply.github.com>
Date: Sun, 28 May 2023 14:42:07 -0500
Subject: [PATCH] Add information about App Management permissions to the FAQ.

---
 docs/FAQ.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/FAQ.md b/docs/FAQ.md
index bc9ec012f7..12f6eea5b0 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -220,3 +220,9 @@ Or use the `--greedy` flag:
     brew upgrade --greedy
 
 Refer to the `upgrade` section of the [`brew` manual page](Manpage.md) for more details.
+
+## Why do my apps lose their Dock position / Launchpad position / permission settings when I run `brew upgrade`?
+
+Homebrew has two possible strategies to update apps: uninstalling the old version and reinstalling the new one, or replacing the contents of the app with the new contents. With the uninstall/reinstall strategy, [macOS thinks the app is being deleted without any intent to reinstall it](https://github.com/Homebrew/brew/pull/15138), and so it removes some internal metadata for the old app, including where it appears in the Dock and Launchpad and which permissions it's been granted. The content replacement strategy works around this by treating the upgrade as an in-place upgrade. However, starting in macOS Ventura, these in-place upgrades are only allowed when the updater application (in this case, the terminal running Homebrew) has [certain permissions granted](https://github.com/Homebrew/brew/pull/15483). Either the "App Management" or "Full Disk Access" permission will suffice.
+
+Homebrew defaults to in-place upgrades when it has the necessary permissions. Otherwise, it will use the uninstall/reinstall strategy.