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

[Nick Coghlan]

On 11 November 2016 at 08:01, Paul Moore <p.f.moore at gmail.com> wrote:
> On 10 November 2016 at 21:18, Ethan Furman <ethan at stoneleaf.us> wrote:
>> On 11/10/2016 01:07 PM, Franklin? Lee wrote:
>>>
>>> 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.
>>
>>
>> +1.  These seem like *really* good ideas to me.
>
> Agreed - I like all of the points made in the post.

Providing some notes on what we currently have along these lines.

In the top level of the devguide, we have:

* https://docs.python.org/devguide/#proposing-changes-to-python-itself

Which links to:

* https://docs.python.org/devguide/stdlibchanges.html
* https://docs.python.org/devguide/langchanges.html
* https://docs.python.org/devguide/faq.html#suggesting-changes

And the FAQ further links to:

* http://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate.html
* http://www.curiousefficiency.org/posts/2011/02/justifying-python-language-changes.html

For PEP level changes, PEP 1 gives some limited guidance when
describing the recommended "Motivation" and "Rationale" sections:
https://www.python.org/dev/peps/pep-0001/#what-belongs-in-a-successful-pep

We don't currently have anything specific linked from the python-ideas
list description, and the above can be a bit hard to follow since it's
scattered across several pages.

We also don't have anything like the document Franklin suggested
explaining Python's feature distribution hierarchy (language features,
standard library features, documented recipes/patterns, bundled
modules, general purpose PyPI modules, project specific utility
modules, private utility modules) and the trade-offs between them
(basically, as you get lower down the stack, your potential
distribution reach goes up, but your rate of change goes down and your
adoption cycles start taking longer). Along the same lines, we don't
currently have anything specifically stating that dependency
management has a non-zero cost and that copying and pasting utility
code into a project specific utility module is sometimes the right
thing to do.

Not specifically related to python-ideas and somewhat dated in the
specifics, but related to the topic of conflict management on the core
design lists, there is also:

* http://www.curiousefficiency.org/posts/2011/04/musings-on-culture-of-python-dev.html

And more recently Brett published a good piece on time and energy
management as a volunteer contributor to open source project
maintenance:

* http://www.snarky.ca/why-i-took-october-off-from-oss-volunteering

So there are probably two different documents that could be helpful if
someone had the time and inclination to draft them based on what we
have already:

- "Creating Effective Change Proposals for Python"
- "Expectations for Contributors to the Python Design Process"

The first would be about constructing good design arguments, and
pointing out the implications of core Python development placing a
significant emphasis on educational use cases (i.e. a way for people
to acquire computational literacy in the first place, not just a way
for us to tell computers what we want them to do) and "incidental
programming" use cases (i.e. a way for folks whose primary expertise
lies in areas other than programming or computer science to
nevertheless be able to automate the routine aspects of their work).

The second would be about setting appropriate boundaries around what's
reasonable for participants to expect from fellow participants
(including explicitly pointing that if folks are looking for a
customer experience rather than a contributor experience, there are
multiple commercial Python redistributors out there willing to sell
them one).

Neither document would need to be perfect - as with many things, we
could start with something relatively simple and iterate from there.

Regards,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia