classification
Title: Add What's New for Idle.
Type: enhancement Stage: resolved
Components: IDLE Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: ncoghlan, ned.deily, serhiy.storchaka, terry.reedy
Priority: normal Keywords:

Created on 2014-07-11 19:56 by terry.reedy, last changed 2015-05-23 22:31 by terry.reedy. This issue is now closed.

Messages (6)
msg222785 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-07-11 19:56
For the stdlib in general, What's New in x.y.0 is sufficient because there is not supposed to be anything new in bugfix releases except for bugfixes.  2.7 has a security enhancement exemption, and a corresponding section in the 2.7 What's New for security enhancements in maintenance releases.

A similar section for Idle could be added to What's New for each Python version.  But thinking about it, I would rather have a separate document listed in the Idle help menu and advertised in the Idle sign-on message. In particular, I would replace the useless "Type "copyright", "credits" or "license()" for more information." with "See HELP/WHAT'S NEW for information about changes in each release."
msg222835 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-07-12 11:28
Isn't IDLE-specific What's New file was merged in general What's New file few years ago?
msg222876 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-07-12 19:58
The Python x.y docs describe the Python x.y language and stdlib, minus Idle (and turtledemo). The Python x.(y+1) What's New describes the delta between Python x.y and x.(y+1) in a user friendly and relevant way.

The Idle model of What's New type changes in every release does not fit the general model. For one thing, instead of all new non-bugfix changes appearing in .0 releases, there will be very few if any really new changes in x.(y+1).0. Almost all changes will have already appeared in some x.y.(z>0) release.

Whatever is supposed to be the situation with Idle news is not working right and would not be sufficient even it did.

What's New in 2.7 has this (and only this) about Idle:
---
PEP 434: IDLE Enhancement Exception for All Branches

PEP 434 describes a general exemption for changes made to the IDLE ...

For details of any IDLE changes, refer to the NEWS file for the specific release.
--
As near as I can tell, the general NEWS file is not easily accessible. So I think that should say 'Idle NEWS file ...., accessible through Help / About Idle'.

However, the 2.7 Idle news.txt file has not been updated since 2.7.5. Last year I suggested that Idle NEWS entries should begin in the idlelib file and be transferred to Misc/NEWS upon release. This was vetoed, and it was claimed that the transfer should and would happen the other way. It is not.

What's New 3.4 has only this about Idle: "Running IDLE with the -n flag (no subprocess) is deprecated. However, the feature will not be removed until issue 18823 is resolved."  For 3.4.1, nothing was added to Idle NEWS. Nothing was added after 3.3.0 either. The update on release is not happening.

Even if Idle news.txt were properly updated, it would not serve the purposes served by What's New and even the html changelog version of Misc/NEWS. The entries are disorganized, unfiltered, duplicated, tied to specific patches rather than user topics, begin with *unlinked* issue numbers, and say too little for the user.  

Unfiltered: most of the recent Idle news entries are about unittest and human test additions. Here is what I might put in a What's New document to cover them all.
---
Idle tests:

An automated unittest suite was started in May 2013. Users can run it with "python -m test -ugui test_idle". Adding "-v" will display the test classes and methods.

A human-operated test suite was started in May 2014. Uses can run it with "python -m idlelib.test_idle.htest. Report problems to the idle-dev mailing list.
---
There are other items that are also not relevant to normal users.

Duplication: if 3.4 news.txt were properly updated release by release, then the items listed for 3.5.0 would be the cumulative list added for 3.4.1 through 3.4.final, plus any 3.5-only user-relevant items that get added (there are none now).

This issue is about adding something that does not exist: an Idle specific file accessible from the idle help menu that it updated as needed with the occasional non-obvious user-relevant changes, especially those that users *need* to read.  An example of the latter is moving the the setting for the formatparagraph extension from config-main to confix-extensions (#20577).
msg222895 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2014-07-12 23:41
"The Python x.y docs describe the Python x.y language and stdlib, minus Idle (and turtledemo). The Python x.(y+1) What's New describes the delta between Python x.y and x.(y+1) in a user friendly and relevant way."

I don't understand "minus IDLE (and turtledemo)".  They look documented to me:
 
https://docs.python.org/3.4/library/idle.html
https://docs.python.org/3.4/library/turtle.html#demo-scripts
https://docs.python.org/2.7/library/idle.html
https://docs.python.org/2.7/library/turtle.html#demo-scripts

"As near as I can tell, the general NEWS file is not easily accessible."

The URL for the NEWS file for each release is included as the "Release Notes" link for each release on https://www.python.org/downloads/.  For Py3 releases since Python 3.3, a formatted HTML version is available, at urls like:

https://docs.python.org/3.4/whatsnew/changelog.html#python-3-4-1

For all current releases, include Py2.7.x, a raw text version is available at urls like:

http://hg.python.org/cpython/raw-file/v2.7.8/Misc/NEWS

I believe it has been suggested before that the NEWS button could open a browser window with the appropriate release-specific URL from above rather than opening a Tk window with news.txt.

"What's New 3.4 has only this about Idle: [...]"

These sections are not immutable.  If the section for a previous release is incomplete, you can update it in the current branch(es).

Rather than duplicating information between IDLE-specific files and the normal Python What's New and NEWS documents, wouldn't it better to just get it done well all in one place?  This doesn't have to be difficult.

In any case, this seems to be pretty much a duplicate of Issue17506 and probably Issue21621.
msg222908 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-07-13 04:14
Ned, Thank you for the turtledemo doc location. I opened #21971 to add it to the module and general indexes and update it with respect to the two_canvases demo.

Neither Idle nor idlelib are in the modules index. The main link for IDLE in the general index goes to the glossary entry. Could that entry have a link to the doc section?

The x.y docs do not describe 'Idle x.y' because there is no 'Idle x.y'. There was, for instance, 'Idle 3.4.0', there is now 'Idle 3.4.1', and there will be 'Idle 3.4.2'. There may not have been any doc-worthy changes in 3.4.1, but I expect there will be in 3.4.2 (and 2.7.9). This reality is the basis of and the reason for this issue and #21621 (which I will come back to).

What is the idle section of the repository and online doc supposed to document? To the best of my knowledge, this has not been discussed, nor any policy written. However, I think the repository doc should be synchronized with the repository code, which would mean documenting unreleased new features.

As far as I know, the current version is an html version of idlelib/help.txt as of 1.5 or more years ago. I have not checked to see if it includes any details that have changed.

The current doc does not have any version-added, or in Idle's case, release-added notes.  Assuming that there is something new since 3.0.0 should it?  I don't think so. If someone conditionally includes a 3.4 feature in 3.3 code, the problem might show up years later. If someone tries to use an Idle feature in a version that lacks it, they won't find it. I think a focused feature log such as proposed in this issue is a better place for release-added update notes.

Having two sources copies of the Idle docs is a nuisance. I would not mind either getting rid of help.txt or replacing it with help.html captured on the release date, and included as a back up for people who do not have web access at a particular time and place.  There is an issue for this already.

As for the update notes. In #21621, I proposed copying the boilerplate announcement in the 2.7 What's New to 3.x. I got no feedback that this is acceptable. In the meanwhile, I have realized that people need the sort of re-written update notes for the rest of the stdlib that currently comprise What's New. I would be happy to put them in What's New itself, as part of patches that add the feature and update the manual. I would then add an option to Help to access the online section of What's New.  Nick, is updating the Idle section of What's New during the maintenance cycle, with per release notes, OK with you?

#17506 was partly about the fact that Idle NEWS items sometimes (always since 3.4.1) do not merge forward properly.  That is a separate issue from this one.
msg243952 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-05-23 22:31
I just added a generic entry to the 3.4 and 3.5 What's New docs pointing people to idlelib/NEWS.txt.  

+  idlelib and IDLE
+----------------
+
+Since idlelib implements the IDLE shell and editor and is not intended for
+import by other programs, it gets improvements with every release. See
+:file:`Lib/idlelib/NEWS.txt` for a cumulative list of changes since 3.4.0,
+as well as changes made in future 3.5.x releases. This file is also available
+from the IDLE Help -> About Idle dialog.
+
History
Date User Action Args
2017-12-04 19:47:12terry.reedylinkissue21621 superseder
2015-05-23 22:31:03terry.reedysetstatus: open -> closed
resolution: fixed
messages: + msg243952

stage: needs patch -> resolved
2014-07-13 04:14:56terry.reedysetnosy: + ncoghlan
messages: + msg222908
2014-07-12 23:41:24ned.deilysetnosy: + ned.deily
messages: + msg222895
2014-07-12 19:58:06terry.reedysetmessages: + msg222876
2014-07-12 11:28:14serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg222835
2014-07-11 19:56:08terry.reedycreate