Opened 5 years ago
Last modified 5 years ago
#30858 closed Cleanup/optimization
Ambiguous phrasing in the Error Reporting documentation — at Version 1
Reported by: | ForgottenLords | Owned by: | nobody |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | Error Reporting, Documentation |
Cc: | Triage Stage: | Accepted | |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | yes | UI/UX: | no |
Description (last modified by )
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.