Merge 8c628b39bd into f000da3b35

doc/040_backup.rst

@@ -751,15 +751,72 @@ snapshot.
 Scheduling backups
 ******************
 
-Restic does not have a built-in way of scheduling backups, as it's a tool
-that runs when executed rather than a daemon. There are plenty of different
-ways to schedule backup runs on various different platforms, e.g. systemd
-and cron on Linux/BSD and Task Scheduler in Windows, depending on one's
-needs and requirements. If you don't want to implement your own scheduling,
-you can use `resticprofile <https://github.com/creativeprojects/resticprofile/#resticprofile>`__.
+.. admonition:: Design note
+
+   Restic intentionally does not provide built-in scheduling or job management.
+   It is designed to run when executed, rather than as a daemon. Scheduling and
+   orchestration are therefore considered out of scope and are delegated to the
+   operating system or external tools.
+
+   This design keeps the restic core simpler, more reliable, and easier to audit,
+   while allowing it to integrate cleanly into a wide range of environments.
+
+Scheduling mechanisms
+=====================
+
+Backup scheduling depends on the platform and environment:
+
+- On Unix-like systems (e.g. BSD, Linux and macOS), ``systemd`` timers are generally preferred when available,
+  as they provide better error handling, logging, dependency management, and
+  integration with the system lifecycle.
+- ``cron`` remains a widely supported and portable option, especially on
+  minimal or non-systemd systems.
+- On Windows, Task Scheduler can be used to run restic commands at defined
+  intervals.
+
+The choice of scheduler depends on the operating system and local constraints,
+rather than on restic itself.
+
+External orchestration tools
+============================
+
+Several community-maintained tools exist to orchestrate restic backups by
+combining configuration, scheduling, hooks, and retention policies. These tools
+are optional and not required to use restic.
+
+Using such tools can reduce boilerplate for some setups, but they are not part
+of restic itself and are not required for correct operation.
+
+.. note::
+
+   Restic is not affiliated with, nor does it endorse, any third-party
+   orchestration or automation tools, even if such tools are mentioned explicitly in the
+   documentation.
+
+If you don't want to implement your own scheduling, you can use third-party
+orchestration tools such as `resticprofile <https://creativeprojects.github.io/resticprofile/>`__.
+
+Avoiding concurrent runs
+========================
+
+.. caution::
+
+   Avoid running overlapping scheduled restic commands against the same
+   repository.
+
+   While the repository format supports concurrent access, some
+   operations require exclusive locks and overlapping runs can cause lock
+   contention, failed backups, or additional maintenance work.
+
+When scheduling restic to run automatically, use mechanisms that prevent overlapping executions.
+Common strategies include:
+
+- ensuring that scheduled jobs cannot overlap
+- using simple locking mechanisms (for example, lock files)
+- relying on the scheduler's own guarantees (such as systemd unit semantics).
+
+See :ref:`locks-design` for details.
 
-When scheduling restic to run recurringly, please make sure to detect already
-running instances before starting the backup.
 
 Space requirements
 ******************

doc/design.rst

@@ -591,6 +591,8 @@ As can be seen from the output of the program ``sha256sum``, the hash
 matches the plaintext hash from the map included in the tree above, so
 the correct data has been returned.
 
+.. _locks-design:
+
 Locks
 =====