"Proposing a change" document? (was: Civility on this mailing list)
(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@gmail.com> wrote:
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.
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?
I don't like that last part. It's sort of prideful, and also unnecessary.
+1. These seem like *really* good ideas to me.
Agreed - I like all of the points made in the post.
Me too. And while we're at it, it would be nice to document the process beyond the early stages -- once there seems to be some support for your idea -- what then? -CHB -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On 11 November 2016 at 08:01, Paul Moore <p.f.moore@gmail.com> wrote:
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.htm... * http://www.curiousefficiency.org/posts/2011/02/justifying-python-language-ch... 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-... 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@gmail.com | Brisbane, Australia
+1. These seem like *really* good ideas to me.
Agreed - I like all of the points made in the post.
Me too. And while we're at it, it would be nice to document the process beyond the early stages -- once there seems to be some support for your idea -- what then? -CHB -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On 11 November 2016 at 08:01, Paul Moore <p.f.moore@gmail.com> wrote:
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.htm... * http://www.curiousefficiency.org/posts/2011/02/justifying-python-language-ch... 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-... 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@gmail.com | Brisbane, Australia
participants (5)
-
Chris Barker -
Ethan Furman -
Franklin? Lee -
Nick Coghlan -
Paul Moore