From f4b7acedbf8dc0ed8fb14b00c9ba955e862512e8 Mon Sep 17 00:00:00 2001
From: Adam Johnson <me@adamj.eu>
Date: Wed, 25 Sep 2019 10:28:08 +0100
Subject: [PATCH] [3.0.x] Documented admonition on when to use custom signals

Thanks Cesar Canassa for the suggestion and Aymeric Augustin for review.
Backport of 566fca14b3e1406f918898de5bb2b2382a44edaf from master
---
 docs/topics/signals.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/topics/signals.txt b/docs/topics/signals.txt
index 817867a4ae..f61dee9f33 100644
--- a/docs/topics/signals.txt
+++ b/docs/topics/signals.txt
@@ -206,6 +206,12 @@ Defining and sending signals
 Your applications can take advantage of the signal infrastructure and provide
 its own signals.
 
+.. admonition:: When to use custom signals
+
+    Signals are implicit function calls which make debugging harder. If the
+    sender and receiver of your custom signal are both within your project,
+    you're better off using an explicit function call.
+
 Defining signals
 ----------------