Ambiguous phrasing in the Error Reporting documentation

[ForgottenLords]

In the ​Error Reporting documentation, the following phrasing is used (Emphasis Mine):

When DEBUG is False, Django will email the users listed in the ADMINS setting whenever your code raises an unhandled exception and results in an internal server error (HTTP status code 500)

Myself and several others in my development team read this as:
Whenever your code raises an unhandled exception resulting in an internal server error

when in actuality it should read more like the following to better reflect the correct behavior of Django:
Whenever your code raises an unhandled exception, or your view returns a response with a status code 500

The nuance is perhaps small, but we had been operating under the assumption that views returning a response with status_code=500 would be 'silent' and not generate emails as they are internal server errors, but have already been correctly and safely handled by our code yet we still want to send the client a 500 error to inform them that the response could not be completed as expected. We assumed based on that line that emails would ONLY be sent as a result of unhandled exceptions.

It may be worth expanding on the error handling to allow users to return 'safe' 500 responses that will not be logged, and in fact Django does check for the _has_been_logged property already before logging the response, which we can set in our code already so perhaps just exposing that to the documentation in a little note would be useful to people who want to send 500 responses without sending emails might be sufficient.

[Carlton Gibson]

I think this is so edge-case to be marginal at best. I've ​suggested a small docs rewording but would be happy to say wontfix.

[Carlton Gibson]

After a quick chat with Mariusz, looks like we'll take the PR. Thanks for the report!

It may be worth expanding on the error handling to allow users to return 'safe' 500 responses that will not be logged, and in fact Django does check for the _has_been_logged property already before logging the response, which we can set in our code already so perhaps just exposing that to the documentation in a little note would be useful to people who want to send 500 responses without sending emails might be sufficient.

I don't think that adding this complication is worth the gain. Users already find logging complicated enough. Those in this particular case can look at log_response(), as you have done.

[Carlton Gibson <carlton@…>]

In 94eae4e5:

Fixed #30858 -- Clarified that AdminEmailHandler processes all 5xx responses.

[Carlton Gibson <carlton.gibson@…>]

In 71489a52:

[3.0.x] Fixed #30858 -- Clarified that AdminEmailHandler processes all 5xx responses.

Backport of 94eae4e5633fbf21f5dcae6e0472ce6a51dd3411 from master

[Carlton Gibson <carlton.gibson@…>]

In 9763ed7a:

[2.2.x] Fixed #30858 -- Clarified that AdminEmailHandler processes all 5xx responses.

Backport of 94eae4e5633fbf21f5dcae6e0472ce6a51dd3411 from master