[New-bugs-announce] [issue13515] Consistent documentation practices for security concerns and considerations

[Nick Coghlan]

New submission from Nick Coghlan <ncoghlan at gmail.com>:

This issue proposes that we adopt and apply some standard practices when documenting modules that have potential security implications and other cross-cutting errors that may affect multiple interfaces within the module.

Accordingly, the main target is the "Documenting Python" meta-docs, proposing the addition of a new subsection to the Style Guide, with an update to the subprocess module documentation serving as the exemplar of a new recommended style:

======================
2.6 Security Considerations (and Other Concerns)
------------------------------------------------

Some modules provided with Python are inherently exposed to security issues (e.g. shell injection vulnerabilities) due to the purpose of the module (e.g. subprocess invocation). Littering the documentation of these modules with red warning boxes for problems that are due to the task at hand, rather than specifically to Python's support for that task, doesn't make for a good reading experience.

Instead, these security concerns should be gathered into a dedicated "Security Considerations" section within the module's documentation, and cross-referenced from the documentation of affected interfaces with in-line text similar to "Please refer to the :ref:`security-considerations` section for important information on how to avoid common mistakes".

Similarly, if there is a common error that affects many interfaces in a module (e.g. OS level pipe buffers filling up and stalling child processes), these can be documented in a "Common Errors" section and cross-referenced rather than repeated for every affected interface.
======================


(based on the thread at http://mail.python.org/pipermail/python-dev/2011-December/114717.html)

----------
assignee: docs at python
components: Documentation
messages: 148710
nosy: docs at python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Consistent documentation practices for security concerns and considerations

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13515>
_______________________________________