[Edu-sig] REQ: HOWTO mailing lists resources

[Wes Turner]

What are some good resources for learning how to mailing list?

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

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/f9cb211e/attachment.html>