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

Jump to bottom

Windows Python 3.7 installer broken by README.txt renamed to README.rst #73765

Closed
vstinner opened this issue Feb 16, 2017 · 17 comments
Closed

Windows Python 3.7 installer broken by README.txt renamed to README.rst #73765

vstinner opened this issue Feb 16, 2017 · 17 comments
Assignees
@zooba
Labels
3.7 (EOL) end of life build The build process and cross-build OS-windows release-blocker

Comments

@vstinner
Copy link
Member

BPO 29579
Nosy @birkenfeld, @pfmoore, @vstinner, @tjguk, @benjaminp, @ned-deily, @zware, @zooba
PRs
  • bpo-29579: Removes readme.txt from the installer. #160
  • bpo-29579: Removes readme.txt from the installer. #161
  • [Do Not Merge] Sample of CPython life with blurb. #703
  • [Do Not Merge] Convert Misc/NEWS so that it is managed by towncrier #552
    		•

    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/zooba'
closed_at = <Date 2017-02-19.03:28:35.644>
created_at = <Date 2017-02-16.09:48:36.332>
labels = ['build', '3.7', 'OS-windows', 'release-blocker']
title = 'Windows Python 3.7 installer broken by README.txt renamed to README.rst'
updated_at = <Date 2017-03-31.16:36:37.299>
user = 'https://github.com/vstinner'

    bugs.python.org fields:

    activity = <Date 2017-03-31.16:36:37.299>
actor = 'dstufft'
assignee = 'steve.dower'
closed = True
closed_date = <Date 2017-02-19.03:28:35.644>
closer = 'steve.dower'
components = ['Build', 'Windows']
creation = <Date 2017-02-16.09:48:36.332>
creator = 'vstinner'
dependencies = []
files = []
hgrepos = []
issue_num = 29579
keywords = []
message_count = 17.0
messages = ['287924', '287925', '287938', '287942', '287951', '288013', '288015', '288028', '288036', '288037', '288039', '288040', '288042', '288093', '288094', '288095', '288190']
nosy_count = 8.0
nosy_names = ['georg.brandl', 'paul.moore', 'vstinner', 'tim.golden', 'benjamin.peterson', 'ned.deily', 'zach.ware', 'steve.dower']
pr_nums = ['160', '161', '703', '552']
priority = 'release blocker'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue29579'
versions = ['Python 3.6', 'Python 3.7']
    @vstinner
    Copy link
    Member Author

    Copy of #104 (comment)
    ---
    The Windows installer build picks up this readme file and distributes it as readme.txt (see Tools/msi/exe/exe_files.wxs, which now needs fixing).

    I vote we should keep both so that we can distribute the file without rst formatting.

    (As an aside, we also read the /LICENSE file, so if someone wants to come in and "fix" that too then they'll also need to update the installer.)
    ---

    README.txt was renamed to README.rst by the PR#2:
    #2

    But README.rst was then modified by PR #70, PR #73 and #21.

    @vstinner vstinner added 3.7 (EOL) end of life build The build process and cross-build OS-windows labels Feb 16, 2017
    @vstinner
    Copy link
    Member Author

    I proposed to convert README.rst to HTML and provide the HTML file in the Windows installer.

    @zooba
    Copy link
    Member

    zooba commented Feb 16, 2017

    I'm okay with including a html readme in the installer, but it has to be fully self-contained with no separate images or style sheets, and can't have any dependencies on reaching the network (until the user clicks a link, obviously).

    My concern with just including the rst file as-is is the formatting, particularly of links, which are now much harder to read and copy than in the txt format.

    In any case, we can't build a release until this is resolved one way or another. Perhaps RMs are happy to maintain the plain text version? Or we should let the github home page version diverge entirely from the actual readme and add back the original file. (I am only concerned about releasing it, so I'd like the people who maintain it to weigh in.)

    @vstinner
    Copy link
    Member Author

    Another option (don't know if it's a good idea or not) is to not
    include any README file in the installer. Is it really worth it? Why
    not pointing to docs.python.org/3.7/ for example? Or suggest to
    install the "Windows help file" package?

    I just checked on my Fedora 25: the python3 package includes
    /usr/share/doc/python3/README file.

    I also checked if any other package include .rst doc: I found a lot of
    them. As you may expect, most Python packages.

    But for example, the "dnf" system tool used to manage packages only
    uses a README.rst file which even includes a reference to an external
    image:
    https://raw.githubusercontent.com/rpm-software-management/dnf/gh-pages/logos/DNF_logo.png

    You can find dnf README file at:
    https://github.com/rpm-software-management/dnf/blob/master/README.rst

    Other examples of packages including reST doc (excluding python*):
    devassistant, koji, vex, fpaste, pypy, git-review, hawkey, subunit,
    libbytesize, etc.

    Ah just to be clear: Fedora packages provide reST as plain text, .rst
    files, not HTML.

    @zooba
    Copy link
    Member

    zooba commented Feb 16, 2017

    I see absolutely no reason to use other projects on github as precedent here, as the developers have likely not made an explicit decision and are just shipping files that they already have. Github may be the home of our development now, but most users don't know or care.

    @zware
    Copy link
    Member

    zware commented Feb 17, 2017

    With the exception of the Travis and Codecov badges, rst2html README.rst produces a nicely self-contained HTML readme.

    However, I'm not sure how useful that readme is on Windows. Perhaps we should draft a new, simple readme for inclusion in the Windows installers that focuses on Python on Windows.

    @zware
    Copy link
    Member

    zware commented Feb 17, 2017

    Another option acceptable to me would be to simply leave out the readme entirely. I wasn't even aware it was included until this issue came up :)

    @ned-deily
    Copy link
    Member

    FWIW, we do not include the top-level README in the macOS installer package. Instead, we supply Mac-installer specific Welcome and Readme files that are displayed by the macOS Installer app during the installation process and the installer Readme is also installed for later reference. These files are also the primary documentation for python.org macOS binary installer changes. I agree with Zach that the top-level README doesn't seem very useful for binary installs.

    @zooba
    Copy link
    Member

    zooba commented Feb 17, 2017

    Okay. Unless someone volunteers to write a Windows specific one, I'll make the change to the installer to leave it out.

    Anyone know how far the change has been backported?

    @zware
    Copy link
    Member

    zware commented Feb 17, 2017

    So far, to 3.6. I don't really expect it to move back to 3.5, and 2.7's README is its own mess.

    @vstinner
    Copy link
    Member Author

    Steve> Anyone know how far the change has been backported?

    Ah, it seems like the README.txt => README.rst change was backported:
    commit 1e8cc88.

    Since it breaks the Windows installer, I suggest to revert this change.

    FYI my first motivation to convert README to reST was to have a nicer
    homepage for http://github.com/python/cpython/ But the homepage uses
    the README of the master branch.

    @zware
    Copy link
    Member

    zware commented Feb 17, 2017

    There were significant corrections to the README in that backport that should not be lost if we do de-restify the 3.6 readme.

    @zooba
    Copy link
    Member

    zooba commented Feb 17, 2017

    I don't think that removing the readme.txt from the install constitutes a breaking change (LICENSE would be a bigger deal), and removing the file from the installer sounds simpler than updating the readme.

    Also, if you choose the 3.6 branch from the GitHub page you'll see whatever readme is in there, hence my thought that it would be backported.

    @zooba zooba self-assigned this Feb 18, 2017
    @zooba
    Copy link
    Member

    zooba commented Feb 18, 2017

    Pull request is at #160 and backport at #161

    @zooba
    Copy link
    Member

    zooba commented Feb 19, 2017

    New changeset 52a7e92 by GitHub in branch 'master':
    bpo-29579: Removes readme.txt from the installer. (#160)
    52a7e92

    @zooba
    Copy link
    Member

    zooba commented Feb 19, 2017

    New changeset d372cda by GitHub in branch '3.6':
    bpo-29579: Removes readme.txt from the installer. (#161)
    d372cda

    @zooba zooba closed this as completed Feb 19, 2017
    @vstinner
    Copy link
    Member Author

    I don't think that removing the readme.txt from the install constitutes a breaking change (LICENSE would be a bigger deal), and removing the file from the installer sounds simpler than updating the readme.

    Ok, fine :-) Happy to see this issue closed ;-)

    @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
    Assignees

    @zooba zooba

    Labels
    3.7 (EOL) end of life build The build process and cross-build OS-windows release-blocker
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    4 participants
    @vstinner @zooba @ned-deily @zware