[Distutils] Improving Communication

[Wes Turner]

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
platform?

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:
@pypa/core



>
> 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
member


>
> * 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
default.


>
> * 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.

[EDIT]

I EDITED THIS.


>   - 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)

```python
__import__('this')
```

These create a trackback on the mentioned issue:

  #1
  pypa/pip#1


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"
https://github.com/sindresorhus/refined-github/pull/1188



>
> 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]
https://github.com/joelparkerhenderson/github_special_files_and_paths


>
> 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>