Fixed #18759 -- updated SECRET_KEY documentation

  Document SECRET_KEY becoming required in 1.5.

  Also expand the description slightly, and add a more prominent warning
  about the security implications of running with an exposed SECRET_KEY.

1 files changed, 17 insertions, 3 deletions

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 531ff33da2..f319a9bee9 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1537,9 +1537,23 @@ SECRET_KEY
 
 Default: ``''`` (Empty string)
 
-A secret key for this particular Django installation. Used to provide a seed in
-secret-key hashing algorithms. Set this to a random string -- the longer, the
-better. ``django-admin.py startproject`` creates one automatically.
+A secret key for a particular Django installation. This is used to provide
+:doc:`cryptographic signing </topics/signing>`, and should be set to a unique,
+unpredictable value.
+
+:djadmin:`django-admin.py startproject <startproject>` automatically adds a
+randomly-generated ``SECRET_KEY`` to each new project.
+
+.. warning::
+
+    **Keep this value secret.**
+
+    Running Django with a known :setting:`SECRET_KEY` defeats many of Django's
+    security protections, and can lead to privilege escalation and remote code
+    execution vulnerabilities.
+
+.. versionchanged:: 1.5
+    Django will now refuse to start if :setting:`SECRET_KEY` is not set.
 
 .. setting:: SECURE_PROXY_SSL_HEADER