[issue15863] Fine-grained info about Python versions which support changes introduced in micro releases
New submission from Alexander Konovalenko: Some security fixes and bug fixes that are simultaneously issued for multiple Python versions require changes to the documentation. I'm now looking at the hash randomization vulnerability that was fixed in 2.6.8 and 2.7.3. The docs always mention the release in which a new feature was added. That's great. But for a security fix such as the bug in question, the set of versions which support it doesn't look like "2.x.y or later". The documentation for the -R command-line option and the PYTHONHASHSEED environment variable says "New in version 2.6.8". A reader who is not familiar with the context would infer that those feature are supported in Python 2.7 through 2.7.2, which is not the case. The docs should say "New in version 2.6.8 and 2.7.3". http://docs.python.org/using/cmdline.html#cmdoption-R http://docs.python.org/using/cmdline.html#envvar-PYTHONHASHSEED The documentation for the sys.flags.hash_randomization attribute says "New in version 2.7.3". Again, that leaves out the version 2.6.8 and future versions in the 2.6.x branch, which presumably support the new attribute. The docs should say "New in version 2.6.8 and 2.7.3". http://docs.python.org/library/sys.html#sys.flags Disclaimer: I did not test the relevant micro releases to see whether they actually support those features. Just checked the release dates and applied common sense. If you know of any other micro release bugfixes that were mentioned in the docs, the same considerations apply to them. Please verify the docs are correct, fix them or file appropriate bugs. ---------- assignee: docs@python components: Documentation messages: 169841 nosy: alexkon, docs@python priority: normal severity: normal status: open title: Fine-grained info about Python versions which support changes introduced in micro releases versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Andrew Svetlov added the comment: Hash randomization is security patch. It is applied to 2.6.8, 2.7.3, 3.2.3 and 3.3. Python doc should not enumerate all affected releases. For example, if you read docs for 2.6 branch it shows you 2.6.8 version only and that's ok. ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Alexander Konovalenko added the comment: Andrew, I don't get it. :( Why not? The docs for Python 2.7 generally inform the reader in which Python version every feature appeared. That's really helpful if your code should run on earlier version of Python. You don't have to dig through the docs for older Python releases and compare them one to another; you can just read the latest docs and all information is there. How is the security patch case different? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Andrew Svetlov added the comment: Well, I can try to make patch. Please note: versionadded tag accepts only single version argument, you have to use couple of tags which looks weird. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Terry J. Reedy added the comment: I do not think there should be references between the Python 2 docs and Python 3 docs. But within each, I think it ok to have exceptional multiple references for what is, I believe, a unique situation: a security fix that required a new feature. Do it however seems most graceful. My first thought was that someone seeing "added in 2.6.8' should know that adding a feature in a bugfix release is almost never done, hence it might not be in 2.7.0. But then I remembered that this fix is mainly for web sites, and the reader selecting which Python versions to use might not be a Python programmer. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Andrew Svetlov added the comment: Well, the patch is welcome. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Georg Brandl added the comment: I don't think this is necessary. ---------- nosy: +georg.brandl resolution: -> works for me status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Andrew Svetlov added the comment: Hash randomization is security patch. It is applied to 2.6.8, 2.7.3, 3.2.3 and 3.3. Python doc should not enumerate all affected releases. For example, if you read docs for 2.6 branch it shows you 2.6.8 version only and that's ok. ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Alexander Konovalenko added the comment: Andrew, I don't get it. :( Why not? The docs for Python 2.7 generally inform the reader in which Python version every feature appeared. That's really helpful if your code should run on earlier version of Python. You don't have to dig through the docs for older Python releases and compare them one to another; you can just read the latest docs and all information is there. How is the security patch case different? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Andrew Svetlov added the comment: Well, I can try to make patch. Please note: versionadded tag accepts only single version argument, you have to use couple of tags which looks weird. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Terry J. Reedy added the comment: I do not think there should be references between the Python 2 docs and Python 3 docs. But within each, I think it ok to have exceptional multiple references for what is, I believe, a unique situation: a security fix that required a new feature. Do it however seems most graceful. My first thought was that someone seeing "added in 2.6.8' should know that adding a feature in a bugfix release is almost never done, hence it might not be in 2.7.0. But then I remembered that this fix is mainly for web sites, and the reader selecting which Python versions to use might not be a Python programmer. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Andrew Svetlov added the comment: Well, the patch is welcome. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
Georg Brandl added the comment: I don't think this is necessary. ---------- nosy: +georg.brandl resolution: -> works for me status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________
participants (4)
-
Alexander Konovalenko -
Andrew Svetlov
-
Georg Brandl
-
Terry J. Reedy