[1.9.x] Fixed #25878 -- Documented requirement that handler404 return a 404 response.

Backport of 49eeb0f570c91af5064d9e4ac8649e9afa0236ec from master

2 files changed, 18 insertions, 8 deletions

diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt
index 1fb9375b79..1d55ba05b6 100644
--- a/docs/ref/urls.txt
+++ b/docs/ref/urls.txt
@@ -183,8 +183,9 @@ A callable, or a string representing the full Python import path to the view
 that should be called if the HTTP client has sent a request that caused an error
 condition and a response with a status code of 400.
 
-By default, this is ``'django.views.defaults.bad_request'``. That default
-value should suffice.
+By default, this is ``'django.views.defaults.bad_request'``. If you
+implement a custom view, be sure it returns an
+:class:`~django.http.HttpResponseBadRequest`.
 
 See the documentation about :ref:`the 400 (bad request) view
 <http_bad_request_view>` for more information.
@@ -198,8 +199,9 @@ A callable, or a string representing the full Python import path to the view
 that should be called if the user doesn't have the permissions required to
 access a resource.
 
-By default, this is ``'django.views.defaults.permission_denied'``. That default
-value should suffice.
+By default, this is ``'django.views.defaults.permission_denied'``. If you
+implement a custom view, be sure it returns an
+:class:`~django.http.HttpResponseForbidden`.
 
 See the documentation about :ref:`the 403 (HTTP Forbidden) view
 <http_forbidden_view>` for more information.
@@ -212,8 +214,9 @@ handler404
 A callable, or a string representing the full Python import path to the view
 that should be called if none of the URL patterns match.
 
-By default, this is ``'django.views.defaults.page_not_found'``. That default
-value should suffice.
+By default, this is ``'django.views.defaults.page_not_found'``. If you
+implement a custom view, be sure it returns an
+:class:`~django.http.HttpResponseNotFound`.
 
 See the documentation about :ref:`the 404 (HTTP Not Found) view
 <http_not_found_view>` for more information.
@@ -227,8 +230,9 @@ A callable, or a string representing the full Python import path to the view
 that should be called in case of server errors. Server errors happen when you
 have runtime errors in view code.
 
-By default, this is ``'django.views.defaults.server_error'``. That default
-value should suffice.
+By default, this is ``'django.views.defaults.server_error'``. If you
+implement a custom view, be sure it returns an
+:class:`~django.http.HttpResponseServerError`.
 
 See the documentation about :ref:`the 500 (HTTP Internal Server Error) view
 <http_internal_server_error_view>` for more information.
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index bc29228881..2c1a4b0d22 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -1147,6 +1147,12 @@ Miscellaneous
   * ``ForeignRelatedObjectsDescriptor`` is ``ReverseManyToOneDescriptor``
   * ``ManyRelatedObjectsDescriptor`` is ``ManyToManyDescriptor``
 
+* If you implement a custom :data:`~django.conf.urls.handler404` view, it must
+  return a response with an HTTP 404 status code. Use
+  :class:`~django.http.HttpResponseNotFound` or pass ``status=404`` to the
+  :class:`~django.http.HttpResponse`. Otherwise, :setting:`APPEND_SLASH` won't
+  work correctly with ``DEBUG=False``.
+
 .. _deprecated-features-1.9:
 
 Features deprecated in 1.9