[Python-ideas] "Proposing a change" document? (was: Civility on this mailing list)

[Franklin? Lee]

(Is that the right way to change subject? Anyway, context here:
https://mail.python.org/pipermail/python-ideas/2016-October/043208.html)

On Fri, Oct 21, 2016 at 11:07 AM, Paul Moore <p.f.moore at gmail.com> wrote:
>
> I wonder. Would there be value in adding a sign-up email to the list
> (supported by a posting of that email to the list, to catch existing
> contributors) that set out some of the basic principles of how changes
> are judged for inclusion in Python?

Turn it around. Have a document outlining how one should _argue_ for
their idea. Instead of, "We get a lot of ideas. Are you SURE your idea
is good?" say, "We WANT to hear your idea, and here is the best way to
get us to listen." A list of reasons why ideas get rejected will make
them defensive, while a list of points they need to prove will put
them on the offensive, and also get them thinking deeply about the
potential costs/issues of their idea.

Encourage arguments with sample code (before and after their change).
Encourage having real-world code (or a stripped-down version of actual
code) and showing how their change makes the code better. Emphasize
_how_ this helps convince others.

I think this attitude will reduce, not increase, the number of posts
(from the people who read the document). It's easier to think, "My
idea is amazing," than to think, "I've demonstrated all that I needed
to." You might also get better-quality posts: instead of _mentally_
going down a checklist, they'd be writing out how their idea fulfills
that checklist.

I'm worried about how the community would self-police with such a
document. Maybe they'll bite harder when someone doesn't follow it.

> * The fact that the default answer is typically "no", along with an
> overview of the reasons *why* the status quo wins by default.

Instead: "Any new feature adds maintenance burden in the code, in the
docs, and in the minds of Python developers. You should show how the
benefits of the feature will outweigh these costs."

(P.S.: I don't believe a lack of implementor is a point against an
idea (except when there's a competing idea). It doesn't further the
discussion for _whether_ the idea is good. It's not unheard of for
ideas to reach PEP status, then stop there because no one will do the
work. Someone can always find the discussion later, see that it's
popular, and decide to work on it. Anyone wanna convince me
otherwise?)

> * Some of the simple "rules of thumb" like "not every 2-line function
> should be a builtin.

That, in particular, is a bad response type. It implies the poster's
supporting arguments are strongly based on having _universal_
consistency, which is rarely the case. In my experience, "not every"
(anti-universal?) counterarguments are usually used against
non-universal arguments, and then you have "I didn't say they did"
responses.

Instead, contrast a few levels of inclusion, like built-ins,
batteries, itertools recipes, PyPI, personal library. Talk about
different scales to measure features, like "broadly useful" and "easy
to specify/understand, but hard to implement".

Have them pick a function or two at the same level of inclusion as
their function, and show that their function measures favorably
against the included function on the given scales.

Have them think about (putting an implementation on) PyPI as a way to
prove that their idea will be useful to people. It's not a backseat to
stdlib, it's the way toward stdlib.

> * Basic reminders that Python is used by a very diverse set of users,
> and proposals that are only beneficial for a limited group need to be
> weighed against the disruption to the majority who get no benefit.

Instead, have them discuss who will benefit from their idea, and what
it will cost everyone else who doesn't need it. In particular, how
would a Python user, especially a novice, learn to read code written
that uses their idea? Do other implementations need to implement this
feature to be compatible with CPython?

> * The above comment, that we welcome ideas because it's important that
> we don't stagnate and having assumptions challenged is valuable, even
> if the bar for getting such ideas accepted is (necessarily) high.

I don't like that last part. It's sort of prideful, and also unnecessary.