From 165a5a7bdf6cac753cd429d44810346821df1646 Mon Sep 17 00:00:00 2001
From: missytake <missytake@systemli.org>
Date: Tue, 12 May 2026 09:48:37 +0200
Subject: [PATCH] docs: document how to upgrade to new version

---
 doc/source/faq.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index cc3c74b1..75eff92f 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -48,6 +48,28 @@ Dovecot, and are configured to run unattended without much maintenance
 effort. Chatmail relays happily run on low-end hardware like a Raspberry
 Pi.
 
+.. _upgrade:
+
+How can I upgrade my chatmail relay?
+------------------------------------
+
+To upgrade to the latest ``main`` branch,
+``cd`` into your local checkout of `https://github.com/chatmail/relay/`_
+and run the following commands:
+
+   ::
+
+       git pull origin main --rebase --autostash
+       scripts/cmdeploy run
+
+If you don't want the latest development version,
+but a specific tagged release like `1.10.0 <https://github.com/chatmail/relay/releases/tag/1.10.0>`_,
+run ``git pull origin 1.10.0`` instead.
+
+If you made local changes for your setup,
+they will be reapplied as long as they conflict with the upgrade.
+If a conflict arises, ``git status`` will tell you how to resolve it.
+
 
 How trustable are chatmail relays?
 ----------------------------------