Below is a draft for a set of patch guidelines. This is meant for that times where people ask "how do a create a patch for a change I made" or where to point people if they created a patch but it comes up short (no tests, etc.). Hopefully this will go up on python.org/dev/ . Let me know of any errors and such. -------------------------- About ///// This set of guidelines is meant for people who have written code that they wish to have committed to the Python programming language. This means that this set of guidelines assumes you have already written code and thus just want to know the steps required to generate the patch necessary to submit your change for addition in Python. The assumption you are using a UNIX-style shell is also made. If you need help with any of these steps, please ask for it! Usually you can create a new patch missing a few steps and the Python developers will try to help you complete it so that your patch can eventuallly be accepted. Guidelines for committing code to Python will be contained in a separate document. .. contents:: Steps to Creating a Patch ///////////////////////// Read the Developer Intro to understand the scope of your proposed change ======================================================================== Changes to Python come in various levels of scope. You could be fixing a simple bug in the standard library. You might be trying to add a new feature to a module. You might even be suggesting a new feature to the language. All three have a different amount of scope and thus require varying amounts of work to get approval. Please read the `Developer Intro`_ doc to make sure you realize the proper scope of what you are doing. It also tells you the rough steps needed for varying types of changes to be accepted. Add the appropriate unit tests ============================== Python prides itself on being a very stable piece of software. We maintain this by having a regression test suite that contains a huge amount of unit tests that exercise both the language and the standard library. Any change you make to Python requires a unit test. If your patch is to fix a bug, then a test exercising that bug and your fix is needed. If it is a new feature then an entirely new regression test might be needed. The important thing is that your new code is exercised within Python's test suite. Add the proper document changes =============================== If your patch will change or add new semantics, you must update the documentation. If your code clarifies some ambiguous behaviour, you must update the docs. The only time you do not need to touch the documentation is if your patch fixes a bug or adds new unit tests. Make your code follow the style guidelines ========================================== `PEP 7`_ and `PEP 8`_ are the style guidelines for C and Python code, respectively. Your code must conform to the style guidelines before it is accepted. Generate a patch ================ In general, people get their copy of the Python source from two locations: a svn checkout or from downloaded source. Both have slightly different steps in terms of generating patches. Working from a svn checkout is the best way to create a patch. It makes it easier on the Python developers since there is less chance of any merge problems. It also raises the chances that a developer will be willing to put the time and effort into working with you and your patch. If you need help with working with svn and Python's repository, see the `Developer FAQ`_. Working from downloaded source is so inferior to working with a svn checkout that it will not be discussed here (although patches *will* be accepted against downloaded code). First step is to update your svn checkout with ``svn update``. Once you have done that and resolved the merge conflicts, generate a patch containing the files you have changed. You can see what files you have touched with ``svn status``. If it lists only modified files you want to include in your patch, you can then generate your patch:: svn diff > PATCH_FILE Make sure to name ``PATCH_FILE`` to a reasonable name and be prepared to upload it in a later step. Also, please note what revision number you are working against. This can be found by executing:: python -c "import sys; print sys.version" Create a tracker item on SourceForge ==================================== First make sure you have a `SourceForge account`_. Once you have one and havve logged in, go to the `SF patch tracker`_ for Python and create a new tracker item. In the new tracker item, set the item's fields as so: * Private Leave unchecked. * Category Set to what area of Python your patch affects. * Group Set to the version of Python that the patch was generated against. * Assigned To Leave as-is. * Priority: Leave as-is. * Summary Briefly describe what the patch does. * Detailed Description Describe in more detail what the patch does. Make sure to mention the revision number the patch is against here. Also mention any bugs that the patch fixes. * Upload and Attach a File Point to the patch you generated. * File Description Mention it is the initial version of the patch. If you end up uploading newer versions of your patch you then specify how it is different from the previous one. Reference the patch in proper bug reports ========================================= If your patch fixes a bug, add a follow-up to that bug report referencing the patch. If there is not bug report but your patch does fix a bug, then quickly create a bug report. Wait for a developer to contact you =================================== At this point you need to wait for a Python developer to come along and look at your patch. This might be a while as all Python developers are volunteers and thus have a limited amount of time. Do not be surprised if it takes weeks or more before your patch is examined. There is a standing offer that if you review five other patches (by commenting on its correctness, helping it meet these guidelines, etc.), then a developer will definitely have a look at any patch you specify. Just email python-dev with what five patches you reviewed (and what you did for the review) and the patch you want examined. .. _Developer Intro: http://www.python.org/dev/intro/ .. _PEP 7: http://www.python.org/dev/peps/pep-0007/ .. _PEP 8: http://www.python.org/dev/peps/pep-0008/ .. _Developer FAQ: http://www.python.org/dev/faq .. _SourceForge account: http://sourceforge.net/account/newuser_emailverify.php .. _SF patch tracker: http://sourceforge.net/tracker/?group_id=5470&atid=305470
On Thu, Aug 24, 2006 at 12:22:42PM -0700, Brett Cannon wrote:
Read the Developer Intro to understand the scope of your proposed change
"Search through the PEPs, developer mailing lists and patches. Has a similar patch already been proposed? Has it been accepted, postponed or rejected? Learn the reasons why it's been postponed or rejected." Oleg. -- Oleg Broytmann http://phd.pp.ru/ phd@phd.pp.ru Programmers don't die, they just GOSUB without RETURN.
On 8/24/06, Oleg Broytmann <phd@oper.phd.pp.ru> wrote:
On Thu, Aug 24, 2006 at 12:22:42PM -0700, Brett Cannon wrote:
Read the Developer Intro to understand the scope of your proposed change
"Search through the PEPs, developer mailing lists and patches. Has a similar patch already been proposed? Has it been accepted, postponed or rejected? Learn the reasons why it's been postponed or rejected."
Oleg. -- Oleg Broytmann http://phd.pp.ru/ phd@phd.pp.ru Programmers don't die, they just GOSUB without RETURN.
Brett,
Below is a draft for a set of patch guidelines.
Thanks for getting around to this!
Wait for a developer to contact you ===================================
At this point you need to wait for a Python developer to come along and look at your patch. This might be a while as all Python developers are volunteers and thus have a limited amount of time. Do not be surprised if it takes weeks or more before your patch is examined.
There is a standing offer that if you review five other patches (by commenting on its correctness, helping it meet these guidelines, etc.), then a developer will definitely have a look at any patch you specify. Just email python-dev with what five patches you reviewed (and what you did for the review) and the patch you want examined.
May I suggest the following wording for this section? This is basically the feedback I found most helpful a few weeks ago; it's more specific about how notification and the 5-for-1 rule work. ================= When you submit your patch, the tracker notifies a mailing list that most core Python developers subscribe to. But remember that Open Source runs on volunteerism and meritocracy. If you are a new Python contributor, then your patch may languish for weeks or more before anyone volunteers a response. Python addresses this barrier to entry with a "5-for-1 rule." Pick five other patches or bugs, try to apply or reproduce them, and then report your results back to the tracker. Then, send a note to python-dev listing the five you reviewed and the patch id of your own patch, and one of Python's "patch angels" will get the ball rolling on your patch. ================= chad
On 8/24/06, Chad Whitacre <chad@zetaweb.com> wrote:
Brett,
Below is a draft for a set of patch guidelines.
Thanks for getting around to this!
Welcome.
Wait for a developer to contact you
===================================
At this point you need to wait for a Python developer to come along and look at your patch. This might be a while as all Python developers are volunteers and thus have a limited amount of time. Do not be surprised if it takes weeks or more before your patch is examined.
There is a standing offer that if you review five other patches (by commenting on its correctness, helping it meet these guidelines, etc.), then a developer will definitely have a look at any patch you specify. Just email python-dev with what five patches you reviewed (and what you did for the review) and the patch you want examined.
May I suggest the following wording for this section? This is basically the feedback I found most helpful a few weeks ago; it's more specific about how notification and the 5-for-1 rule work.
=================
When you submit your patch, the tracker notifies a mailing list that most core Python developers subscribe to. But remember that Open Source runs on volunteerism and meritocracy. If you are a new Python contributor, then your patch may languish for weeks or more before anyone volunteers a response.
Python addresses this barrier to entry with a "5-for-1 rule." Pick five other patches or bugs, try to apply or reproduce them, and then report your results back to the tracker. Then, send a note to python-dev listing the five you reviewed and the patch id of your own patch, and one of Python's "patch angels" will get the ball rolling on your patch.
=================
Changed the wording slightly, but I mostly ended up using your text: When you submit your patch, the tracker notifies a mailing list that most core Python developers subscribe to of the creation of your new patch. But remember that Open Source runs on volunteerism and meritocracy. Your patch may languish for weeks or more before anyone volunteers a response because of limited time on the part of Python developers. Python addresses this barrier to entry with a "5-for-1 rule." Pick five other patches or bugs, review them, and then report your results back to the tracker. Then, send a note to python-dev listing the five you reviewed and the patch id of your own patch, and a Python developer will take a look at your patch. -Brett
Brett,
When you submit your patch, the tracker notifies a mailing list that most core Python developers subscribe to of the creation of your new patch.
Isn't "of the creation of your new patch" redundant? What else would it be notifying the list of?
Your patch may languish for weeks or more before anyone volunteers a response because of limited time on the part of Python developers.
I think this is less accurate. Patches languish because of limited time *and* because newbies don't have any social capital w/in the Python community. New patch contributors are volunteers too, so they understand that constraint. Their big problem is their outsider status, to which the patch angels/5-for-1 system is an elegant solution. And that's what should be emphasized in this FAQ. In other words, I still prefer my wording. But since I'm a newbie with little merit, I'll be content with whatever you decide. :) chad
On 8/27/06, Chad Whitacre <chad@zetaweb.com> wrote:
Brett,
When you submit your patch, the tracker notifies a mailing list that most core Python developers subscribe to of the creation of your new patch.
Isn't "of the creation of your new patch" redundant? What else would it be notifying the list of?
Yep, slightly.
Your patch may languish for weeks or more before anyone volunteers a
response because of limited time on the part of Python developers.
I think this is less accurate. Patches languish because of limited time *and* because newbies don't have any social capital w/in the Python community. New patch contributors are volunteers too, so they understand that constraint. Their big problem is their outsider status, to which the patch angels/5-for-1 system is an elegant solution. And that's what should be emphasized in this FAQ.
But that makes us sound elitist. In other words, I still prefer my wording. But since I'm a newbie with
little merit, I'll be content with whatever you decide. :)
OK. =) -Brett
Brett,
I think this is less accurate. Patches languish because of limited time *and* because newbies don't have any social capital w/in the Python community. New patch contributors are volunteers too, so they understand that constraint. Their big problem is their outsider status, to which the patch angels/5-for-1 system is an elegant solution. And that's what should be emphasized in this FAQ.
But that makes us sound elitist.
To be honest I took away the opposite lesson. New patch contributors acutely feel their outsider status; this is to be expected in any social system. The fact that there is a clear, established path for newcomers to follow -- the 5-for-1 rule -- is precisely what makes the Python community non-elitist in this instance. Transparent documentation on this point would further erode any elitism. chad
participants (3)
-
Brett Cannon -
Chad Whitacre -
Oleg Broytmann