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

Stale Python Language Reference docs (no walrus). #84049

Closed
brandtbucher opened this issue Mar 5, 2020 · 20 comments
Closed

Stale Python Language Reference docs (no walrus). #84049

brandtbucher opened this issue Mar 5, 2020 · 20 comments
Labels
3.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir easy

Comments

@brandtbucher
Copy link
Member

BPO 39868
Nosy @gvanrossum, @emilyemorehouse, @miss-islington, @brandtbucher, @shankarj67
PRs
  • bpo-39868: Update Language Reference for PEP 572. #18793
  • [3.8] bpo-39868: Update Language Reference for PEP 572. (GH-18793) #18797
  • bpo-39868: Add the documentation for Assignment Expressions (PEP 572). #18851
  • [3.9] bpo-39868: Add documentation for Assignment Expressions (walrus, PEP 572) (GH-18851) #21622
  • [3.8] bpo-39868: Add documentation for Assignment Expressions (walrus, PEP 572) (GH-18851) #21623
    		•

    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 = None
closed_at = <Date 2020-07-25.23:55:37.229>
created_at = <Date 2020-03-05.21:54:08.320>
labels = ['easy', '3.8', '3.9', '3.10', 'docs']
title = 'Stale Python Language Reference docs (no walrus).'
updated_at = <Date 2020-07-25.23:55:37.227>
user = 'https://github.com/brandtbucher'

    bugs.python.org fields:

    activity = <Date 2020-07-25.23:55:37.227>
actor = 'gvanrossum'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-07-25.23:55:37.229>
closer = 'gvanrossum'
components = ['Documentation']
creation = <Date 2020-03-05.21:54:08.320>
creator = 'brandtbucher'
dependencies = []
files = []
hgrepos = []
issue_num = 39868
keywords = ['patch', 'easy']
message_count = 20.0
messages = ['363456', '363462', '363464', '363465', '363467', '363473', '363483', '363484', '363489', '363507', '363509', '363516', '363562', '363589', '363617', '363660', '374294', '374295', '374296', '374297']
nosy_count = 6.0
nosy_names = ['gvanrossum', 'docs@python', 'emilyemorehouse', 'miss-islington', 'brandtbucher', 'shankarj67']
pr_nums = ['18793', '18797', '18851', '21622', '21623']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue39868'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']
    @brandtbucher
    Copy link
    Member Author

    It looks like https://docs.python.org/3/reference/expressions.html and https://docs.python.org/3/reference/compound_stmts.html were never updated for named expressions.

    Because this change has to be backported, it's sort of a blocker for my PEP-614 doc updates in bpo-39702, which need to use the missing node in 3.9 only (I'd rather have this get a clean backport now than a messy one later)!

    Is somebody more familiar with PEP-572 willing to take this? Should be pretty straightforward.

    Pinging Emily since it looks like you've done some grammar/doc work for this in the past.

    @brandtbucher brandtbucher added the 3.8 only security fixes label Mar 5, 2020
    @brandtbucher brandtbucher added docs Documentation in the Doc dir easy 3.8 only security fixes labels Mar 5, 2020
    @brandtbucher brandtbucher added docs Documentation in the Doc dir easy labels Mar 5, 2020
    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 5, 2020

    Can I take this issue?

    @brandtbucher
    Copy link
    Member Author

    Sorry, I hadn't seen your comment... :(

    I've already finished the grammar specification bit, but not the prose description of how assignment expressions work, etc.

    How about I leave that empty in my PR and you can actually do the documentation part afterward that's merged? Cool? I'd be happy to review it.

    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 6, 2020

    Thank you for that!!!

    Can you please provide some pointers to what exactly I have to do?

    @brandtbucher
    Copy link
    Member Author

    Of course. After my PR is merged, you can make another PR that replaces the ".. TODO: BPO-39868" line with a description of how assignment expressions work. Likely much of the language can be borrowed from the PEP.

    Let me know if you need help with any of the steps. Have you written RST / made a CPython PR on GitHub before?

    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 6, 2020

    This is my first contribution to Python. This is why I am looking for some guidance, just point me to some resource, and then I will look into it thoroughly.

    I am reading this https://www.python.org/dev/peps/pep-0572/ for better understanding.

    @gvanrossum
    Copy link
    Member

    New changeset 8bae219 by Brandt Bucher in branch 'master':
    bpo-39868: Update Language Reference for PEP-572. (bpo-18793)
    8bae219

    @miss-islington
    Copy link
    Contributor

    New changeset 0c71770 by Miss Islington (bot) in branch '3.8':
    bpo-39868: Update Language Reference for PEP-572. (GH-18793)
    0c71770

    @brandtbucher
    Copy link
    Member Author

    Thanks for offering to help, Shankar! For this change, you can look at the other sections of the Doc/reference/expressions.rst file for an idea of what we're looking for. I think a few sentences and maybe a small code snippet should probably be fine.

    The devguide has all of the information that you need to get started. Specifically, you'll want to look at:

    Also, you should sign the CLA *as soon as possible* (https://www.python.org/psf/contrib/contrib-form/)!

    Once you've made a PR, please request a review from me so I can make sure it moves along quickly. Let me know if you have any questions... I know it can be really tricky at first!

    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 6, 2020

    Thank you for helping me out brandtbucher.

    As per my understanding, I am looking into the code (https://github.com/python/cpython/blob/master/Doc/reference/expressions.rst) and finding where the code doesn't follow the pattern described in (https://www.python.org/dev/peps/pep-0572/.)

    Please let me know if I am correct so that I will quickly go through everything and send you a pull request as soon as possible.

    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 6, 2020

    I am also checking your commit for this: (8bae219) and see that you are changing the "expression: to "assignment_expression".

    Do I have to fill what assignment expression does with some examples?

    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 6, 2020

    I got it that I have to fill the "Assignment expression" section in the code. I am working on it and send you the for review once I am done.

    @brandtbucher
    Copy link
    Member Author

    Great. Just replacing the TODO line with your new description (and maybe an example) should be perfect!

    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 7, 2020

    I have created my draft with an example but I am confused about where exactly do I have to add the code and push it.

    I have cloned these two repositories in my system and setup everything:
    https://github.com/python/cpython
    https://github.com/python/devguide

    1. Please tell me where I should be adding my code. Do I have to add code here https://github.com/python/cpython/blob/master/Doc/reference/expressions.rst and push it?

    2. I am working on the master branch only. Is there any specific branch I have to select?

    @brandtbucher
    Copy link
    Member Author

    I have created my draft with an example but I am confused about where exactly do I have to add the code and push it.

    I have cloned these two repositories in my system and setup everything:
    https://github.com/python/cpython
    https://github.com/python/devguide

    Great! It's not necessary to clone the devguide though; CPython is the only one you're going to edit.

    Make sure you've "forked" the repo on GitHub, and are working on a local clone of your fork. Otherwise things will be trickier.

    1. Please tell me where I should be adding my code. Do I have to add code here https://github.com/python/cpython/blob/master/Doc/reference/expressions.rst and push it?

    Yes, you'll add the new documentation to line 1652, where the "TODO" comment is. You should make the changes in your own fork of the repo, and push. Then you'll be ready for a PR.

    1. I am working on the master branch only. Is there any specific branch I have to select?

    Working from master in your own fork is fine, but frequent contributors often prefer to branch from master and work on those branches instead.

    The pages I've linked to in the devguide walk you through every step of making a PR (including an intro on how to use Git). If it's easier for you, though, you can attach a copy of your edits to this issue and I can make a PR on your behalf. I just wouldn't count on repeating that workflow if you plan on contributing in the future; regular contributors should feel comfortable branching, committing, opening a PR, etc.

    @shankarj67
    Copy link
    Mannequin

    shankarj67 mannequin commented Mar 8, 2020

    I have added the pull request: #18851. Please check it out and let me know if I need to change anything.

    Thank you everyone for your guidance.

    @gvanrossum
    Copy link
    Member

    New changeset f117cef by Shankar Jha in branch 'master':
    bpo-39868: Add documentation for Assignment Expressions (walrus, PEP-572) (bpo-18851)
    f117cef

    @miss-islington
    Copy link
    Contributor

    New changeset 616734b by Miss Islington (bot) in branch '3.9':
    bpo-39868: Add documentation for Assignment Expressions (walrus, PEP-572) (GH-18851)
    616734b

    @miss-islington
    Copy link
    Contributor

    New changeset 755cb49 by Miss Islington (bot) in branch '3.8':
    bpo-39868: Add documentation for Assignment Expressions (walrus, PEP-572) (GH-18851)
    755cb49

    @gvanrossum
    Copy link
    Member

    Congratulations SHANKAR JHA. Thank you for your contribution.

    @gvanrossum gvanrossum added 3.9 only security fixes 3.10 only security fixes labels Jul 25, 2020
    @gvanrossum gvanrossum added 3.9 only security fixes 3.10 only security fixes labels Jul 25, 2020
    @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
    No one assigned
    Labels
    3.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir easy
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @gvanrossum @miss-islington @brandtbucher