diff --git a/committing.rst b/committing.rst --- a/committing.rst +++ b/committing.rst @@ -44,6 +44,61 @@ making a complete patch. +Handling Others' Code +--------------------- + +As a core developer you will occasionally want to commit a patch created by +someone else. When doing so you will want to make sure of some things. + +First, make sure the patch is in a good state. Both :ref:`patch` and +:ref:`helptriage` +explain what is to be expected of a patch. Typically patches that get cleared by +triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS`` +entries. + +Second, make sure the patch does not break backwards-compatibility without a +good reason. This means :ref:`running the test suite ` to make sure +everything still passes. It also means that if semantics do change there must +be a good reason for the breakage of code the change will cause (and it +**will** break someone's code). If you are unsure if the breakage is worth it, +ask on python-dev. + +Third, ensure the patch is attributed correctly by adding the contributor's +name to ``Misc/ACKS`` if they aren't already there (and didn't add themselves +in their patch) and by mentioning "Patch by " in the ``Misc/NEWS`` entry +and the checkin message. If the patch has been heavily modified then "Initial +patch by " is an appropriate alternate wording. + +If you omit correct attribution in the initial checkin, then update ``ACKS`` +and ``NEWS`` in a subsequent checkin (don't worry about trying to fix the +original checkin message in that case). + + +Contributor Licensing Agreements +-------------------------------- + +It's unlikely bug fixes will require a `Contributor Licensing Agreement`_ +unless they touch a *lot* of code. For new features, it is preferable to +ask that the contributor submit a signed CLA to the PSF as the associated +comments, docstrings and documentation are far more likely to reach a +copyrightable standard. + +For Python sprints we now recommend collecting CLAs as a matter of course, as +the folks leading the sprints can then handle the task of scanning (or otherwise +digitising) the forms and passing them on to the PSF secretary. (Yes, we +realise this process is quite archaic. Yes, we're in the process of fixing +it. No, it's not fixed yet). + +As discussed on the PSF Contribution_ page, it is the CLA itself that gives +the PSF the necessary relicensing rights to redistribute contributions under +the Python license stack. This is an additional permission granted above and +beyond the normal permissions provided by the chosen open source license. + +.. _Contribution: http://www.python.org/psf/contrib/ +.. _Contributor Licensing Agreement: + http://www.python.org/psf/contrib/contrib-form/ + + NEWS Entries ------------ @@ -130,11 +185,12 @@ If "closes" (or "closed", or "closing") is prepended, the issue is automatically closed as "fixed". -Working with Mercurial_ ------------------------ +Committing with Mercurial +========================= -As a core developer, the ability to push changes to the official Python -repositories means you have to be more careful with your workflow: +This section provides guidance to core developers on using Mercurial_ to +commit changes. As a core developer, the ability to push changes to the official +Python repositories means you have to be more careful with your workflow: * You should not push new named branches to the main repository. You can still use them in clones that you use for development of patches; you can @@ -203,61 +259,6 @@ .. _eol extension: http://mercurial.selenic.com/wiki/EolExtension -Handling Others' Code ---------------------- - -As a core developer you will occasionally want to commit a patch created by -someone else. When doing so you will want to make sure of some things. - -First, make sure the patch is in a good state. Both :ref:`patch` and -:ref:`helptriage` -explain what is to be expected of a patch. Typically patches that get cleared by -triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS`` -entries. - -Second, make sure the patch does not break backwards-compatibility without a -good reason. This means :ref:`running the test suite ` to make sure -everything still passes. It also means that if semantics do change there must -be a good reason for the breakage of code the change will cause (and it -**will** break someone's code). If you are unsure if the breakage is worth it, -ask on python-dev. - -Third, ensure the patch is attributed correctly by adding the contributor's -name to ``Misc/ACKS`` if they aren't already there (and didn't add themselves -in their patch) and by mentioning "Patch by " in the ``Misc/NEWS`` entry -and the checkin message. If the patch has been heavily modified then "Initial -patch by " is an appropriate alternate wording. - -If you omit correct attribution in the initial checkin, then update ``ACKS`` -and ``NEWS`` in a subsequent checkin (don't worry about trying to fix the -original checkin message in that case). - - -Contributor Licensing Agreements --------------------------------- - -It's unlikely bug fixes will require a `Contributor Licensing Agreement`_ -unless they touch a *lot* of code. For new features, it is preferable to -ask that the contributor submit a signed CLA to the PSF as the associated -comments, docstrings and documentation are far more likely to reach a -copyrightable standard. - -For Python sprints we now recommend collecting CLAs as a matter of course, as -the folks leading the sprints can then handle the task of scanning (or otherwise -digitising) the forms and passing them on to the PSF secretary. (Yes, we -realise this process is quite archaic. Yes, we're in the process of fixing -it. No, it's not fixed yet). - -As discussed on the PSF Contribution_ page, it is the CLA itself that gives -the PSF the necessary relicensing rights to redistribute contributions under -the Python license stack. This is an additional permission granted above and -beyond the normal permissions provided by the chosen open source license. - -.. _Contribution: http://www.python.org/psf/contrib/ -.. _Contributor Licensing Agreement: - http://www.python.org/psf/contrib/contrib-form/ - - Forward-Porting ---------------