Re: Python Documentation, Python language improvement, and productive discussion (Antoine Pitrou)
I'm interested in being part of said Docs group! David ________________________________ From: python-dev-request@python.org <python-dev-request@python.org> Sent: Thursday, July 2, 2020 5:33 PM To: python-dev@python.org <python-dev@python.org> Subject: Python-Dev Digest, Vol 204, Issue 23 Send Python-Dev mailing list submissions to python-dev@python.org To subscribe or unsubscribe via the World Wide Web, visit https://mail.python.org/mailman3/lists/python-dev.python.org/ or, via email, send a message with subject or body 'help' to python-dev-request@python.org You can reach the person managing the list at python-dev-owner@python.org When replying, please edit your Subject line so it is more specific than "Re: Contents of Python-Dev digest..." Today's Topics: 1. Re: Python Documentation, Python language improvement, and productive discussion (Antoine Pitrou) 2. Re: Recent PEP-8 change (Antoine Pitrou) 3. Re: Re Re: Recent PEP-8 change (Ivan Pozdeev) (Ivan Pozdeev) ---------------------------------------------------------------------- Date: Fri, 3 Jul 2020 00:10:04 +0200 From: Antoine Pitrou <solipsis@pitrou.net> Subject: [Python-Dev] Re: Python Documentation, Python language improvement, and productive discussion To: python-dev@python.org Message-ID: <20200703001004.0fca6c23@fsol> Content-Type: text/plain; charset=US-ASCII On Thu, 02 Jul 2020 20:41:54 -0000 "Carol Willing" <willingc@willingconsulting.com> wrote:
Earlier this year at the Python Language Summit, Ned Batchelder and I presented the concept of a Documentation Workgroup and a vision for the next few years:
- Slidedeck https://speakerdeck.com/willingc/cpython-documentation-the-next-5-years - Blog post https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html
Due to some health issues that I have had the past few months, I haven't yet set up the workgroup. It's a priority of mine for July. We will have an open call for workgroup participants.
Kudos for doing this. Having a consistent editorial direction for the documentation is a great idea. Regards Antoine. ------------------------------ Date: Fri, 3 Jul 2020 00:15:29 +0200 From: Antoine Pitrou <solipsis@pitrou.net> Subject: [Python-Dev] Re: Recent PEP-8 change To: python-dev@python.org Message-ID: <20200703001529.2c9ff416@fsol> Content-Type: text/plain; charset=US-ASCII On Thu, 02 Jul 2020 17:58:44 -0400 Random832 <random832@fastmail.com> wrote:
On Thu, Jul 2, 2020, at 05:20, Antoine Pitrou wrote:
We're not talking about posting "your own writing", we're talking about comments (and presumably documentation) in a collective software project. There's a need for consistency, however it's specified and achieved.
Otherwise why stop at English? I could just as well write my comments in French if it's all about individual freedom. Requiring English is not inclusive, it forced people like me to painfully adapt to a language I wasn't used to. And that has nothing to do with "white supremacy".
Why indeed?
No contention to the contrary, but as a routine, post-merge git history= rewrite, not a grand plan, from what I understand.
Oh the other hand, an 'official' comment on the commit, recognising the= issue with the original commit message, the following discussion,=20 and any conclusions that get reached, might be better, in my opinion. I=
'historical' history, as a rule (as opposed to git history). I think si= milar damage is done in this case, when the record, and opportunity=20 to point to and learn from it, is erased.
David
On Fri, Jul 3, 2020 at 4:09 AM David Mertz <mertz@gnosis.cx> wrote:
An issue is that commit messages are uneditable after merge, so som= ething written somewhere suggesting consideration of this would be=20 a good idea, with authors/mergers bearing this in mind, however unusual= a change on this basis would be. This would be additional burden=20 on the core dev team, but if commitment is to be made to inclusivity, i= t might be what's necessary.
I don't think so. https://docs.github.com/en/github/committing-chang= es-to-your-project/changing-a-commit-message. Interactive rebasing=20 is perfectly possible, isn't it. I admit my git-fu isn't that strong, b= ut I've done something that I *think* is the same as this.=A0 It's=20
--------------------------------------------------- Date: Thu, 2 Jul 2020 21:33:56 +0300 From: Ivan Pozdeev <vano@mail.mipt.ru> Subject: [Python-Dev] Re: Recent PEP-8 change (Antoine Pitrou) To: python-dev@python.org Message-ID: <e1d9900a-6dae-8bfc-ad0f-a1512cfa87ab@mail.mipt.ru> Content-Type: text/plain; charset=3Dutf-8; format=3Dflowed On 02.07.2020 21:20, Chris Angelico wrote: possible I'm missing some distinction between the trees I've modified a= nd the current one, but I don't think so.
When you do that sort of rewriting, you're constructing a new and independent history and then saying "hey, this is the history I want everyone to respect now, thanks". It's full-on Back To The Future stuff, and can have annoying or serious consequences with everyone wh= o has a clone or fork of the repo.
It would be extremely annoying to anyone who has an open PR at the time of the rewrite, but the annoyance would be temporary (hopefully one-off).
If you are talking about rewriting the PEP8 commit, it has proven to ca= use so much damage that this is warranted despite the=20 inconveniences IMO.
ChrisA _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@=
Code of Conduct: http://python.org/psf/codeofconduct/ <http://python.= org/psf/codeofconduct/> -- Regards, Ivan
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@py=
Because we're talking about PEP 8, and PEP 8 intends to cover the code style used when writing code in the *Python standard library*. I don't think other Python core developers would like to read code with comments written in French (or, indeed, in Russian or Japanese or...). We're not talking about third-party projects, which indeed choose whatever style and language suit them. Regards Antoine. ------------------------------ Date: Fri, 3 Jul 2020 01:32:38 +0300 From: Ivan Pozdeev <vano@mail.mipt.ru> Subject: [Python-Dev] Re: Re Re: Recent PEP-8 change (Ivan Pozdeev) To: python-dev@python.org Message-ID: <c822aca3-0270-bbba-6f12-99381efc51a2@mail.mipt.ru> Content-Type: multipart/alternative; boundary="------------0905C79342DDD68A7F40BFCF" This is a multi-part message in MIME format. --------------0905C79342DDD68A7F40BFCF Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: quoted-printable At https://git-scm.com/book/en/v2/Git-Branching-Rebasing#_rebase_vs_merge= , they say that the argument of whether to allow overwriting=20 history in VCSes stems from two opposing views on what a project's histor= y should be. One is that is shall be a raw, unedited record of=20 events as they happened; the other is that is should be a (polished and a= dapted for future reading) story of how the project was made. While I'm firmly in camp story (long story short, it makes history much m= ore useful for everything except playing the blame game), in this=20 case, there's a case-specific reason, too. The remarks that stem the controversy have nothing to do with commit's in= tent in technical terms: clarifying wording that cause=20 misunderstanding. They were simply speculations by the author (and misgui= ded ones at that since Strunk & White are actually names). Leaving this commit as it is will leave no trace of any "comment on the c= ommit" and later discussion to a future onlooker. And as a commit=20 is the official codebase, it will still appear as endorsed by the dev tea= m. There'd be no clue that this is not the "final" thoughts on the=20 matter and there something else, somewhere else, and who knows where. While editing the message to just state facts (clarifying the wording) an= d omit specuilations, it will still serve its purpose -- while=20 stating the actual, valid, endorsed by the team (since the concensus is t= hat the change itself was useful and should not be reverted but=20 could be improved further, as a separate initiative), clean from speculat= ions intent of the edit. On 02.07.2020 23:17, David Antonini wrote: prefer to recognise and critique, rather than erase, python.org/message/A2XBFOH5WGEOASSXHHKRWEHMZBN625SU/ thon.org/message/ZZKGBAROR7TR2M7TM4EYSIIHXTUBQB4Y/
Code of Conduct: http://python.org/psf/codeofconduct/ --=20 Regards, Ivan
--------------0905C79342DDD68A7F40BFCF Content-Type: text/html; charset=windows-1252 Content-Transfer-Encoding: quoted-printable <html> <head> <meta http-equiv=3D"Content-Type" content=3D"text/html; charset=3Dwindows-1252"> </head> <body> <font size=3D"2"><span style=3D"font-size:11pt">At <a class=3D"moz-txt-link-freetext" href=3D"https://git-scm.com/bo= ok/en/v2/Git-Branching-Rebasing#_rebase_vs_merge">https://git-scm.com/boo= k/en/v2/Git-Branching-Rebasing#_rebase_vs_merge</a>, they say that the argument of whether to allow overwriting history in VCSes stems from two opposing views on what a project's history should be. One is that is shall be a raw, unedited record of events as they happened; the other is that is should be a (polished and adapted for future reading) story of how the project was made.</span></font> <p><font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt">While I'm firmly i= n camp story (long story short, it makes history much more useful for everything except playing the blame game), in this case, there's a case-specific reason, too.</span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt">The remarks that s= tem the controversy have nothing to do with commit's intent in technical terms: clarifying wording that cause misunderstanding. They were simply speculations by the author (and misguided ones at that since </span></font><font size=3D"2"><span style=3D"font-size:11pt"><font size=3D"2"><span style=3D"font-size:11pt">Strunk & White are actually names</span></font></span></font><font size=3D"2"><span style=3D"font-size:11pt">).</span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></p> <p>Leaving this commit as it is will leave no trace of any "<font size=3D"2"><span style=3D"font-size:11pt">comment on the commit" = and later discussion to a future onlooker. And as a commit is the official codebase, it will still appear as endorsed by the dev team. There'd be no clue that this is not the "final" thoughts on the matter and there something else, somewhere else, and who knows where.<br> </span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt"></span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt">While editing the message to just state facts (clarifying the wording) and omit specuilations, it will still serve its purpose -- while stating the actual, valid, endorsed by the team (since the concensus is that the change itself was useful and should not be reverted but could be improved further, as a separate initiative), clean from speculations intent of the edit.<br> </span></font></p> <p><font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></p> <p><br> </p> <div class=3D"moz-cite-prefix">On 02.07.2020 23:17, David Antonini wrote:<br> </div> <blockquote type=3D"cite" cite=3D"mid:YQXPR0101MB0872D86CFBD9CACAB41E4E4EB26D0@YQXPR0101MB0872.CANP= RD01.PROD.OUTLOOK.COM"> <meta http-equiv=3D"Content-Type" content=3D"text/html; charset=3Dwindows-1252"> <style type=3D"text/css" style=3D"display:none;"> P {margin-top:0;m= argin-bottom:0;} </style> <div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> <div> <div> <div> <div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> <font size=3D"2"><span style=3D"font-size:11pt">No contention to the contrary, but as a routine, post-merge git history rewrite, not a grand plan, from what I understand.</span></font></div> <div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> <font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></div> <div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> <font size=3D"2"><span style=3D"font-size:11pt">Oh the ot= her hand, an 'official' comment on the commit, recognising the issue with the original commit message, the following discussion, and any conclusions that get reached, might be better, in my opinion. I prefer to recognise and critique, rather than erase, <br> </span></font></div> <div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> <font size=3D"2"><span style=3D"font-size:11pt">'historic= al' history, as a rule (as opposed to git history). I think similar damage is done in this case, when the record, and opportunity to point to and learn from it, is erased. <br> </span></font></div> <div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> <font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></div> <div style=3D"font-family: Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);"> <font size=3D"2"><span style=3D"font-size:11pt">David<br> </span></font></div> <div><font size=3D"2"><span style=3D"font-size:11pt"><br> </span></font></div> <div><font size=3D"2"><span style=3D"font-size:11pt">------= ---------------------------------------------<br> </span></font></div> <div><font size=3D"2"><span style=3D"font-size:11pt">Date: Thu, 2 Jul 2020 21:33:56 +0300<br> </span></font></div> <div><font size=3D"2"><span style=3D"font-size:11pt">From: Ivan Pozdeev <a class=3D"moz-txt-link-rfc2396E" href=3D= "mailto:vano@mail.mipt.ru"><vano@mail.mipt.ru></a><br> Subject: [Python-Dev] Re: Recent PEP-8 change (Antoine Pitrou)<br> To: <a class=3D"moz-txt-link-abbreviated" href=3D"mai= lto:python-dev@python.org">python-dev@python.org</a><br> Message-ID: <a class=3D"moz-txt-link-rfc2396E" href=3D"mailto:e1d= 9900a-6dae-8bfc-ad0f-a1512cfa87ab@mail.mipt.ru"><e1d9900a-6dae-8bfc-ad= 0f-a1512cfa87ab@mail.mipt.ru></a><br> Content-Type: text/plain; charset=3Dutf-8; format=3Dflowed<br> </span></font></div> </div> </div> </div> <div> <div> <div> <div><font size=3D"2"><span style=3D"font-size:11pt">On 02.07.2020 21:20, Chris Angelico wrote:<br> </span></font></div> </div> </div> </div> <div> <div> <div><font size=3D"2"><span style=3D"font-size:11pt">> On Fri, Jul 3, 2020 at 4:09 AM David Mertz <a class=3D"moz-txt-link-rfc2396E" href=3D"mailto:mertz= @gnosis.cx"><mertz@gnosis.cx></a> wrote:<br> >>> An issue is that commit messages are uneditable after merge, so something written somewhere suggesting consideration of this would be a good idea, with authors/mergers bearing this in mind, however unusual a change on this basis would be. This would be additional burden on the core dev team, but if commitment is to be made to inclusivity, it might be what's necessary.<br> >><br> >> I don't think so. <a href=3D"https://docs.github.com/en/github/committing-changes-to-your-proj= ect/changing-a-commit-message" target=3D"_blank" rel=3D"noopener noreferrer" moz-do-not-send=3D"true"> https://docs.github.com/en/github/committing-changes-to-your-project/chan= ging-a-commit-message</a>.=A0 Interactive rebasing is perfectly possible, isn't it.=A0 I admit my git-fu isn't that strong, but I've done something that I *think* is the same as this.=A0 It's possible I'm missing some distinction between the trees I've modified and the current one, but I don't think so.<br> >><br> > When you do that sort of rewriting, you're constructing a new and<br> > independent history and then saying "hey, this is the history I want<br> > everyone to respect now, thanks". It's full-on Back To The Future<br> > stuff, and can have annoying or serious consequences with everyone who<br> > has a clone or fork of the repo.<br> ><br> > It would be extremely annoying to anyone who has an open PR at the<br> > time of the rewrite, but the annoyance would be temporary (hopefully<br> > one-off).<br> <br> <br> If you are talking about rewriting the PEP8 commit, it has proven to cause so much damage that this is warranted despite the inconveniences IMO.<br> <br> > ChrisA<br> > _______________________________________________<br=
> Python-Dev mailing list -- <a class=3D"moz-txt-lin= k-abbreviated" href=3D"mailto:python-dev@python.org">python-dev@python.or= g</a><br> > To unsubscribe send an email to <a class=3D"moz-txt-link-abbreviated" href=3D"mailto:py= thon-dev-leave@python.org">python-dev-leave@python.org</a><br> > <a href=3D"https://mail.python.org/mailman3/lists/python= -dev.python.org/" target=3D"_blank" rel=3D"noopener noreferrer" moz-do-not-send=3D"true"> https://mail.python.org/mailman3/lists/python-dev.python.org/</a><br> > Message archived at <a href=3D"https://mail.python.org/archives/list/python-dev@python.org/messa= ge/A2XBFOH5WGEOASSXHHKRWEHMZBN625SU/" target=3D"_blank" rel=3D"noopener noreferrer" moz-do-not-send=3D"true"> https://mail.python.org/archives/list/python-dev@python.org/message/A2XBF= OH5WGEOASSXHHKRWEHMZBN625SU/</a><br> > Code of Conduct: <a href=3D"http://python.org/psf/codeofconduct/" target=3D"_blank" rel=3D"noopener noreferrer" moz-do-not-send=3D"true"> http://python.org/psf/codeofconduct/</a><br> > -- <br> > Regards,<br> > Ivan</span></font></div> </div> </div> <br> </div> <br> <br> <fieldset class=3D"mimeAttachmentHeader"></fieldset> <pre class=3D"moz-quote-pre" wrap=3D"">____________________________= ___________________ Python-Dev mailing list -- <a class=3D"moz-txt-link-abbreviated" href=3D"= mailto:python-dev@python.org">python-dev@python.org</a> To unsubscribe send an email to <a class=3D"moz-txt-link-abbreviated" hre= f=3D"mailto:python-dev-leave@python.org">python-dev-leave@python.org</a> <a class=3D"moz-txt-link-freetext" href=3D"https://mail.python.org/mailma= n3/lists/python-dev.python.org/">https://mail.python.org/mailman3/lists/p= ython-dev.python.org/</a> Message archived at <a class=3D"moz-txt-link-freetext" href=3D"https://ma= il.python.org/archives/list/python-dev@python.org/message/ZZKGBAROR7TR2M7= TM4EYSIIHXTUBQB4Y/">https://mail.python.org/archives/list/python-dev@pyth= on.org/message/ZZKGBAROR7TR2M7TM4EYSIIHXTUBQB4Y/</a> Code of Conduct: <a class=3D"moz-txt-link-freetext" href=3D"http://python= .org/psf/codeofconduct/">http://python.org/psf/codeofconduct/</a> </pre> <div class=3D"moz-signature">-- <br> Regards,<br> Ivan</div> </blockquote> </body> </html> --------------0905C79342DDD68A7F40BFCF-- ------------------------------ Subject: Digest Footer _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ ------------------------------ End of Python-Dev Digest, Vol 204, Issue 23 *******************************************
participants (1)
-
David Antonini