[Edu-sig] Python teacher notes, preparing for class...

[Wes Turner]

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