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@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@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@gmail.com> wrote:
On Thursday, August 30, 2018, kirby urner <kirby.urner@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