Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add What's New for Idle. #66160

Closed
terryjreedy opened this issue Jul 11, 2014 · 6 comments
Closed

Add What's New for Idle. #66160

terryjreedy opened this issue Jul 11, 2014 · 6 comments
Assignees
Labels
topic-IDLE type-feature A feature request or enhancement

Comments

@terryjreedy
Copy link
Member

BPO 21961
Nosy @terryjreedy, @ncoghlan, @ned-deily, @serhiy-storchaka

Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

Show more details

GitHub fields:

assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2015-05-23.22:31:03.348>
created_at = <Date 2014-07-11.19:56:08.027>
labels = ['expert-IDLE', 'type-feature']
title = "Add What's New for Idle."
updated_at = <Date 2015-05-23.22:31:03.347>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2015-05-23.22:31:03.347>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2015-05-23.22:31:03.348>
closer = 'terry.reedy'
components = ['IDLE']
creation = <Date 2014-07-11.19:56:08.027>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 21961
keywords = []
message_count = 6.0
messages = ['222785', '222835', '222876', '222895', '222908', '243952']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'ncoghlan', 'ned.deily', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21961'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

@terryjreedy
Copy link
Member Author

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."

@terryjreedy terryjreedy self-assigned this Jul 11, 2014
@terryjreedy terryjreedy added topic-IDLE type-feature A feature request or enhancement labels Jul 11, 2014
@serhiy-storchaka
Copy link
Member

Isn't IDLE-specific What's New file was merged in general What's New file few years ago?

@terryjreedy
Copy link
Member Author

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 bpo-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 (bpo-20577).

@ned-deily
Copy link
Member

"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 bpo-17506 and probably bpo-21621.

@terryjreedy
Copy link
Member Author

Ned, Thank you for the turtledemo doc location. I opened bpo-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 bpo-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 bpo-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?

bpo-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.

@terryjreedy
Copy link
Member Author

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.
+

@ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
topic-IDLE type-feature A feature request or enhancement
Projects
None yet
Development

No branches or pull requests

3 participants