[Distutils] Improving Communication

Wes Turner wes.turner at gmail.com
Fri Apr 20 22:53:55 EDT 2018

On Friday, April 20, 2018, Donald Stufft <donald at stufft.io> wrote:

> Currently in the packaging space, we have a number of avenues for
> communication, which are:
> - distutils-sig
> - pypa-dev
> - virtualenv-users
> - Other project specific mailing lists
> - IRC
> - gitter
> - Various issue trackers spread across multiple platforms.
> - Probably more places I’m not remembering.

Is there something like a collaboration plan with a decision tree / flow
chart / list of what types of communications are best communicated on which

GitHub Team Discussions [1]
- threaded
- editable
- trackbackable (I think?)
- @user notifications
- email replies
- cross-repo
- public / team-only
- Unfortunately, they're not real time like IRC/Gitter

[1] https://blog.github.com/2017-11-20-introducing-team-discussions/

> The result of this is that all discussion ends up being super fractured
> amongst the various places. Sometimes that is exactly what you want (for
> instance, someone who is working on the wheel specs probably doesn’t care
> about deprecation policy and internal module renaming in pip) and sometimes
> that ends up being the opposite of what you want (for instance, when you’re
> describing something that touches PyPI, setuptools, flit, pip, etc all at
> once).
> Theoretically the idea is that distutils-sig is where cross project
> reaching stuff goes, IRC/gitter is where real time discussion goes, and the
> various project mailing lists and issue trackers are where the project
> specific bits go. The problem is that often times doesn’t actually happen
> in practice except for the largest and most obvious of changes.

"Please refer to the communications flowchart: [url]"

> I think our current “communications stack” kind of sucks, and I’d love to
> figure out a better way for us to handle this that solves the sort of weird
> “independent but related” set of projects we have here.

Do GitHub project boards help?

Team email and web notifications on GitHub work like this:

> From my POV, a list of our major problems are:
> * Discussion gets fractured across a variety of platforms and locations,
> which can make it difficult to actually keep up with what’s going on but
> also to know how to loop in someone relevant if their input would be
> valuable. You have to more or less simultaneously know someone’s email,
> Github username, IRC nick, bitbucket username, etc to be able to bring
> threads of discussion to people’s attention.

A collaboration plan might include this contact information for each team

> * It’s not always clear to users where a discussion should go, often times
> they’ll come to one location and need to get redirected to another
> location. If any discussion did happen in the incorrect location, it tends
> to need to get restarted in the new location (and depending on the specific
> platform, it may be impossible to actually redirect everyone over to the
> proper location, so you again, end up fractured with the discussion
> happening in two places).

IDK how many times we've discussed upgrading mailman to add per message
footer links to relayed messages. Google Groups has this feature on by

> * A lot of the technology in this stack is particularly old, and lacks a
> lot of the modern day affordances that newer things have. An example is
> being able to edit a discussion post to fix typos that can hinder the
> ability of others to actually understand whats being talked about. In your
> typical mailing list or IRC there’s no mechanism by which you can edit an
> already sent message, so your only option is to either let the problem ride
> and hope it doesn’t trip up too many people, or send an additional message
> to correct the error. However these show up as additional, later messages
> which someone might not even see until they’ve already been thoroughly
> confused by the first message (since people tend to read email/IRC in a
> linear fashion).

Issues, Pull Requests, Wikis, and Team Discussions are all editable.



>   - There is a lot of things in this one, other things are things like
> being able to control in a more fine grained manner what email you’re going
> to get.

One can unsubscribe from issue notifications

>   - Holy crap, formatting and typography to make things actually readable
> and not a big block of plaintext.

This is a fenced code block in Markdown and GFM: (GitHub Flavored Markdown)


These create a trackback on the mentioned issue:


This sends notifications to each mentioned user according to their GitHub
notification settings:

  /cc @westurner @dstufft @pypa/core

> * We don’t have a clear way for users to get help, leaving users to treat
> random issues, discussion areas, etc as a support forum, rather than some
> place that’s actually optimized for that. Some of this ties back into some
> of the earlier things too, where it’s hard to actually redirect discussions

- Search org/project/issues [2]
- Search stack overflow,
- Create an issue

[2] https://github.com/sindresorhus/refined-github
"Display possibly related issues on the 'New Issue' page"

> These aren’t *new* problems, and often times the existing members of a
> community are the least effected becasue they’ve already spent effort
> learning the ins and outs and also curating a (typically custom) workflow
> that they’ve grown accustomed too. The problem with that is that often
> times that means that new users are left out, and the community gets
> smaller and smaller as time goes on as people leave and aren’t replaced
> with new blood, because they’re driven off but the issues with the stack.

Is this in the contributing docs? In CONTRIBUTING.rst [3]

Are there standard ISSUE_TEMPLATE/name.md and PULL_REQUEST_TEMPLATE/name.md
? [3]

> A big part of the place this is coming from, is me sitting back and
> realizing that I tend to be drawn towards pulling discussions into Github
> issues rather than onto the varying mailing lists, not because that’s
> always the most appropriate place for it, but because it’s the least
> painful place in terms of features and functionality. I figure if I’m doing
> that, when I already have a significant investment in setting up tooling
> and being involved here, that others (and particularly new users) are
> likely feeling the same way.

A bot that watches the [mailing lists,] and adds issue/PR trackbacks might
be super useful.

Each service has information access optimizations that people like most.
GitHub is designed for software development. These days, I send feature
requests to support at github.com with an "ENH: ..." subject line.

> - Donald
> _______________________________________________
> Distutils-SIG maillist  -  Distutils-SIG at python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20180420/db04f59b/attachment-0001.html>

More information about the Distutils-SIG mailing list