[Edu-sig] REQ: HOWTO mailing lists resources

[Wes Turner]

On Thursday, August 30, 2018, Wes Turner <wes.turner at gmail.com> wrote:

>
> Was: "Re: [Edu-sig] Python teacher notes, preparing for class..."
>

Here's a link to the thread this is forked from:
https://mail.python.org/pipermail/edu-sig/2018-August/012007.html

https://markmail.org/search/?q=list%3Aorg.python.edu-sig#query:list%3Aorg.python.edu-sig+page:1+mid:wbvjeinflkndz4ey+state:results



> On Thursday, August 30, 2018, Wes Turner <wes.turner at gmail.com> wrote:
>
>> Mailing list tips and tricks, PEPs, Write the Docs
>>
>> Since you asked, although this isn't in scope of the original subject
>> line, and since I'd like to just continue this thread instead of breaking
>> the thread by changing the subject line, and since this isn't technically
>> OT (off-topic) in the interest of conversing toward an objective, here I've
>> added a first-line summary of this message. I should probably change the
>> subject and start a new thread.
>>
>> You can search mailing lists in a number of ways:
>>
>> - Google search with "site:mail.python.org" and/or "inurl:" queries
>>   https://www.google.com/search?q=site%3Amail.python.org
>>   (inurl doesn't match mm3-migrated lists too)
>>
>> - Google Groups, if the list is set up there too
>>
>> - Gmail "list:python.org" queries
>>   - This doesn't find messages that you didn't receive because you
>> weren't subscribed yet.
>>
>> - "from:list at mail.python.org" queries
>>   - This doesn't find messages that you didn't receive because you
>> weren't subscribed yet.
>>
>> - Markmail "list:org.python.edu-sig" queries
>>   https://markmail.org/search/?q=list%3Aorg.python
>>   https://markmail.org/search/?q=list%3Aorg.python.edu-sig
>>
>> The Python mailing lists aren't yet all upgraded to mailman 3 (/mm3/
>> URLs); so some lists have the classic mailman archive interface (where "by
>> thread" breaks at the month boundary, for example) and upgraded lists have
>> the new Django-based HyperKitty interface with e.g. search and a full
>> thread view.
>>
>> With mm3, it's also possible to reply to threads you didn't receive
>> because you weren't subscribed at the time.
>>
>> e.g. -- for example
>> i.e. -- that is
>> (List of acronyms OTOH/OTOMH)
>>
>> Reply-all is unnecessary, but often helpful. If you just click reply, it
>> may be addressed off-list to only the sender (and not the list email
>> address, which is what you want if you want the mailing list app to archive
>> for and relay the message to every subscriber). If that happens, you (or
>> the recipient) can forward the message to the list, but it'll be
>> unnecessarily quote-indented unless you just copy and paste (which can be
>> lossy with HTML quote indents inferred from plaintext-quoted lines that
>> start with '>'), so it pays to verify the to: field before you start
>> composing a message.
>>
>> Some old hands argue for like 72 character fixed width messages so that
>> when they're n-levels quote-indented, they still fit on an 80 character
>> terminal without rewrapping. Old-school email clients like mutt, for
>> example, can handle this;
>> though, on a phone, fixed width hard-broken lines
>> wrap like
>> this sometimes; which is not as easy to read.
>>
>> TL;DR (too long; didn't read) is an acronym of Reddit; though the
>> standard form of intro summary, body, conclusion summary is equally helpful
>> for long-form mailing list posts. Many email clients show the first part of
>> the first line of the message after the overly-long narrowly descriptive
>> subject line that doesn't actually describe the scope of the discussion
>> anymore.
>>
>> For Python features, the ultimate objective is to write or develop a PEP.
>> There is a PEP template here:
>> https://www.python.org/dev/peps/pep-0012/
>> https://github.com/python/peps/blob/master/pep-0012.rst
>>
>> PEP 1 explains PEPs:
>> "PEP 1 -- PEP Purpose and Guidelines"
>> https://www.python.org/dev/peps/pep-0001/
>> https://github.com/python/peps/blob/master/pep-0001.txt
>>
>> PEPs must be justified (as indicated by the Rationale heading in the PEP
>> template); so starting with a justification is a good approach to arguing
>> that you need the whole list's time before you spend your precious time
>> writing an actual PEP like actual contributors do sometimes (when they're
>> getting actual work done).
>>
>> Bug and issue discussions are for the issue tracker (Roundup), though
>> sometimes it's a really good idea to ask a list for help and feedback.
>>
>> Mailing lists don't support ReStructuredText, but docs, docstrings, and
>> PEPs do; so it's perfectly reasonable -- even advisable, though not at all
>> strictly necessary -- to format mailing list messages that would be helpful
>> for those purposes in reStructuredText from the start. By the time you've
>> added RST setext headings, you might as well be collaboratively drafting a
>> PEP.
>>
>> Though it doesn't happen nearly frequently enough, it's often really
>> helpful to update the docs with wisdom culled from the mailing lists (and
>> Q&A sites which have labels).
>>
>> "6. Helping with Documentation¶"
>> https://devguide.python.org/docquality/
>>
>> "7. Documenting Python¶"
>> https://devguide.python.org/documenting/
>>
>> The ultimate source of Python documentation (an often-cited strength of
>> Python as a language choice):
>> https://github.com/python/cpython/tree/master/Doc
>>
>> "16. Accepting Pull Requests¶"
>> https://devguide.python.org/committing/
>>
>>
>>
>> On Thursday, August 30, 2018, Wes Turner <wes.turner at gmail.com> wrote:
>>
>>>
>>>
>>> On Thursday, August 30, 2018, kirby urner <kirby.urner at gmail.com> wrote:
>>>>
>>>>
>>>> Thanks.  Yes, I'll add some links to the docs as you suggest.  Great
>>>> feedback!
>>>>
>>>
>>> Glad to be helpful.
>>>
>>> I've trimmed out the text I'm not replying to and tried to use plaintext
>>> only in order to: make sure the thread stays below the 40K limit, and make
>>> it easy to reply inline without breaking HTML tags.
>>>
>>>
>>>>
>>>> Actually as part of my class I'm showing them edu-sig and other
>>>> python.org lists, so we were actually viewing this conversation.  I'll
>>>> extend that to showing your corrections, as I want to demonstrate how the
>>>> Python community all teaches each other, is friendly and so on.
>>>>
>>>
>>> Code review with pull requests / merge requests and GitHub, Gerrit,
>>> GitLab etc is an essential skill.
>>>
>>> Src: https://github.com/jupyter/nbdime
>>> Docs: https://nbdime.readthedocs.io/
>>>
>>> > nbdime provides tools for diffing and merging of Jupyter Notebooks.
>>>
>>> There are a number of real-time collaborative platforms for working with
>>> notebooks (CoCalc, Colab, )
>>>
>>> https://hypothes.is highlights and annotations work on anything with a
>>> URL, are threaded, and support Markdown.
>>>
>>>
>>>>
>>>> Kirby
>>>>
>>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/edu-sig/attachments/20180830/6dbc78b3/attachment-0001.html>