classification
Title: Fine-grained info about Python versions which support changes introduced in micro releases
Type: Stage:
Components: Documentation Versions: Python 2.7, Python 2.6
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: docs@python Nosy List: alexkon, asvetlov, docs@python, georg.brandl, terry.reedy
Priority: normal Keywords:

Created on 2012-09-04 22:44 by alexkon, last changed 2013-10-08 18:46 by georg.brandl. This issue is now closed.

Messages (7)
msg169841 - (view) Author: Alexander Konovalenko (alexkon) Date: 2012-09-04 22:44
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.
msg169915 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-09-06 13:32
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.
msg169916 - (view) Author: Alexander Konovalenko (alexkon) Date: 2012-09-06 13:40
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?
msg169918 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-09-06 13:47
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.
msg170010 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-09-07 19:47
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.
msg170011 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-09-07 19:56
Well, the patch is welcome.
msg199234 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-08 18:46
I don't think this is necessary.
History
Date User Action Args
2013-10-08 18:46:39georg.brandlsetstatus: open -> closed

nosy: + georg.brandl
messages: + msg199234

resolution: works for me
2012-09-07 19:56:17asvetlovsetmessages: + msg170011
2012-09-07 19:47:07terry.reedysetnosy: + terry.reedy
messages: + msg170010
2012-09-06 13:47:54asvetlovsetmessages: + msg169918
2012-09-06 13:40:32alexkonsetmessages: + msg169916
2012-09-06 13:32:19asvetlovsetnosy: + asvetlov
messages: + msg169915
2012-09-04 22:44:19alexkoncreate