On Friday, April 20, 2018, Donald Stufft <donald@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@github.com with an "ENH: ..." subject line.
 

- Donald

_______________________________________________
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig