diff --git a/committing.rst b/committing.rst index 1265ff11e..b932952ba 100644 --- a/committing.rst +++ b/committing.rst @@ -57,54 +57,8 @@ passes before merging any code changes. Patch checklist ''''''''''''''' -Along with running the tests, a simple automated patch checklist, ``patchcheck``, -guides a developer through the common patch generation checks. To run -``patchcheck``: - - On *UNIX* (including Mac OS X):: - - make patchcheck - - On *Windows* (after any successful build):: - - python.bat Tools/scripts/patchcheck.py - -The automated patch checklist runs through: - -* Are there any whitespace problems in Python files? - (using ``Tools/scripts/reindent.py``) -* Are there any whitespace problems in C files? -* Are there any whitespace problems in the documentation? - (using ``Tools/scripts/reindent-rst.py``) -* Has the documentation been updated? -* Has the test suite been updated? -* Has an entry under ``Misc/NEWS.d/next`` been added? -* Has ``Misc/ACKS`` been updated? -* Has ``configure`` been regenerated, if necessary? -* Has ``pyconfig.h.in`` been regenerated, if necessary? - -The automated patch check doesn't actually *answer* all of these -questions. Aside from the whitespace checks, the tool is -a memory aid for the various elements that can go into -making a complete patch. - - -Commit Style ------------- - -.. move this to pullrequest - -Once a change patch is ready and tested, it can be committed to the repository. -We usually prefer to put a whole feature or bugfix into a single commit, but no -more. In particular: - -* Do **not** fix more than one issue in the same commit (except, of course, if - one code change fixes all of them). -* Do **not** do cosmetic changes to unrelated code in the same commit as some - feature/bugfix. - -It is of course okay to pile up several commits to one branch and merge them -into another in one commit. +You should also :ref:`run patchcheck ` to perform a quick +sanity check on the changes. Handling Others' Code @@ -238,37 +192,6 @@ allowed here because news entries are meant to be as readable as possible unprocessed.) -Commit Messages ---------------- - -.. move to pullrequest - -Every commit has a commit message to document why a change was made and to -communicate that reason to other core developers. Python core developers have -developed a standard way of formatting commit messages that everyone is -expected to follow. - -Our usual convention mimics that used in news entries (it is actually common to -start by pasting the news entry into the commit message). The only key -difference when compared to a news entry is the inclusion of the issue number -as the beginning of the commit message. Here is an example:: - - bpo-42: the spam module is now more spammy. - - The spam module sporadically came up short on spam. This change - raises the amount of spam in the module by making it more spammy. - - Thanks to Monty Python for the patch. - -The first line or sentence is meant to be a dense, to-the-point explanation -of what the purpose of the commit is. If this is not enough detail for a commit, -a new paragraph(s) can be added to explain in proper depth what has happened -(detail should be good enough that a core developer reading the commit message -understands the justification for the change). Also, if a non-core developer -contributed to the resolution, it is good practice to credit them. - - - Working with Git_ ================= diff --git a/pullrequest.rst b/pullrequest.rst index f447b6b1b..e0a8ce5f2 100644 --- a/pullrequest.rst +++ b/pullrequest.rst @@ -4,43 +4,126 @@ Lifecycle of a Pull Request =========================== -Creating --------- +Introduction +------------ CPython uses a workflow based on pull requests. What this means is that you create a branch in Git, make your changes, push those changes -to GitHub, and then create a pull request. -`GitHub's help pages `_ are good and there -are tons of pages out there for help with Git. As such, this -document does not go into any great detail as the assumption is there -is a resource out there which will explain things in a way that makes -sense for you personally when it comes to general Git and GitHub -details. +to your fork on GitHub (``origin``), and then create a pull request against +the official CPython repository (``upstream``). -Tool Setup -'''''''''' +.. _pullrequest-quickguide: + +Quick Guide +----------- + +`Clear communication`_ is key to contributing to any project, especially an +`Open Source`_ project like CPython. + +Here is a quick overview of how you can contribute to CPython: + +#. `Create an issue`_ that describes your change [*]_ + +#. :ref:`Create a new branch in Git ` + +#. Work on changes (e.g. fix a bug or add a new feature) + +#. :ref:`Run tests ` and ``make patchcheck`` + +#. :ref:`Commit ` and :ref:`push ` + changes to your GitHub fork + +#. `Create Pull Request`_ on GitHub to merge a branch from your fork + +#. Review and address `comments on your Pull Request`_ + +#. When your changes are merged, you can :ref:`delete the PR branch + ` + +#. Celebrate contributing to CPython! :) + +.. [*] If an issue is trivial (e.g. typo fixes), or if an issue already exists, + you can skip this step. + +.. _Clear communication: https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution +.. _Open Source: https://opensource.guide/ +.. _create an issue: https://bugs.python.org/ +.. _CPython: https://github.com/python/cpython +.. _use HTTPS: https://help.github.com/articles/which-remote-url-should-i-use/ +.. _Create Pull Request: https://help.github.com/articles/creating-a-pull-request/ +.. _comments on your Pull Request: https://help.github.com/articles/commenting-on-a-pull-request/ + + +.. _pullrequest-steps: + +Step-by-step Guide +------------------ + +You should have already :ref:`set up your system `, +:ref:`got the source code `, and :ref:`built Python `. + +* Create a new branch in your local clone:: + + git checkout -b upstream/master + +* Make changes to the code, and use ``git status`` and ``git diff`` to see them. + + (Learn more about :ref:`good-prs`) + +* Make sure the changes are fine and don't cause any test failure:: + + make patchcheck + ./python -m test + + (Learn more about :ref:`patchcheck` and about :doc:`runtests`) + +* Once you are satisfied with the changes, add the files and commit them:: + + git add + git commit -m '' + + (Learn more about :ref:`good-commits`) + +* Then push your work to your GitHub fork:: + + git push origin + +* If someone else added new changesets and you get an error:: + + git fetch upstream + git rebase upstream/master + git push --force origin -.. _workflow: +* Finally go on :samp:`https://github.com/{}/cpython`: you will + see a box with the branch you just pushed and a green button that allows + you to create a pull request against the official CPython repository. -If you have not already done so, you will want to fork the -`CPython repository`_. You can read GitHub's documentation on how to -`fork a repository `_ -if you are not already familiar with how to do this. This will make -sure that you have a clone of your fork of CPython on your computer -and the appropriate remote repositories. +* When people start adding review comments, you can address them by switching + to your branch, making more changes, committing them, and pushing them to + automatically update your PR:: -You will then want to create a branch to contain your work. GitHub has -instructions on how to -`create a branch `_ -within your fork through their website. + git checkout + # make changes and run tests + git add + git commit -m '' + git push origin +* After your PR has been accepted and merged, you can :ref:`delete the branch + `:: -.. _CPython repository: https://github.com/python/cpython + git branch -D # delete local branch + git push origin -d # delete remote branch +.. note:: + You can still upload a patch to bugs.python.org_, but the GitHub pull request + workflow is **strongly** preferred. -Preparation -''''''''''' + +.. _good-prs: + +Making Good PRs +--------------- When creating a pull request for submission, there are several things that you should do to help ensure that your pull request is accepted. @@ -76,111 +159,67 @@ Fifth, proper :ref:`documentation ` additions/changes should be included. -.. _patch-generation: - -Generation -'''''''''' - -To perform a quick sanity check on your changes, you can run:: - - make patchcheck - -This will check and/or fix various common things people forget to do for -pull requests, such as adding any new files needed for the pull request to work -(note that not all checks apply to non-core developers). On Windows, use this -command (after any successful build of Python):: - - python.bat Tools/scripts/patchcheck.py - -.. _pullrequest-quickguide: - -Quick Guide -''''''''''' - -`Clear communication`_ is key to contributing to any project, especially an -`Open Source`_ project like CPython. - -Here is a quick overview of how you can contribute to CPython on GitHub: - -#. If an issue doesn't exist, `create an Issue`_ that describes your change. - Trivial issues (e.g. typo fixes) do not require any issue to be created. - -#. :ref:`Get started ` and set up your system - -#. :ref:`Fork CPython ` (using the Fork button in the - upper-right on GitHub) - -#. :ref:`Clone your GitHub fork and add an "upstream" remote ` - -#. :ref:`Build Python ` on your system - -#. :ref:`Run tests ` after you have built Python +.. _patchcheck: -#. :ref:`Create a Branch in Git ` where you can work on - changes +``patchcheck`` +-------------- -#. :ref:`Run tests ` again +``patchcheck`` is a simple automated patch checklist that guides a developer +through the common patch generation checks. To run ``patchcheck``: -#. :ref:`Commit ` and :ref:`push ` - changes to your GitHub fork - -#. `Create Pull Request`_ on GitHub to merge a branch from your fork - -#. Review and address `comments on your Pull Request`_ - -#. When your changes are merged, you can :ref:`delete the PR branch ` - -#. Celebrate contributing to CPython! :) - -.. _Clear communication: https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution -.. _Open Source: https://opensource.guide/ -.. _create an Issue: https://bugs.python.org/ -.. _CPython: https://github.com/python/cpython -.. _use HTTPS: https://help.github.com/articles/which-remote-url-should-i-use/ -.. _Create Pull Request: https://help.github.com/articles/creating-a-pull-request/ -.. _comments on your Pull Request: https://help.github.com/articles/commenting-on-a-pull-request/ - - -.. _pullrequest-steps: - -Quick Guide Step-by-step -'''''''''''''''''''''''' - -Set up your system (using SSH, or you can `use HTTPS`_):: + On *UNIX* (including Mac OS X):: - git clone git@github.com:YOUR_GITHUB_ID/cpython.git + make patchcheck -Replace ``YOUR_GITHUB_ID`` with your GitHub account name above, then add -main CPython repository as upstream:: + On *Windows* (after any successful build):: - git remote add upstream git://github.com/python/cpython.git + python.bat Tools/scripts/patchcheck.py -Work on new features or fixes:: +The automated patch checklist runs through: - git checkout -b MY_BRANCH_NAME upstream/master +* Are there any whitespace problems in Python files? + (using ``Tools/scripts/reindent.py``) +* Are there any whitespace problems in C files? +* Are there any whitespace problems in the documentation? + (using ``Tools/scripts/reindent-rst.py``) +* Has the documentation been updated? +* Has the test suite been updated? +* Has an entry under ``Misc/NEWS.d/next`` been added? +* Has ``Misc/ACKS`` been updated? +* Has ``configure`` been regenerated, if necessary? +* Has ``pyconfig.h.in`` been regenerated, if necessary? -As you work, commit changes:: +The automated patch check doesn't actually *answer* all of these +questions. Aside from the whitespace checks, the tool is +a memory aid for the various elements that can go into +making a complete patch. - git commit -Then fetch upstream to see if anything conflicts with your changes:: +.. _good-commits: - git fetch upstream +Making Good Commits +------------------- -Then push your work to your clone on GitHub:: +Each feature or bugfix should be addressed by a single pull request, +and for each pull request there may be several commits. In particular: - git push origin MY_BRANCH_NAME +* Do **not** fix more than one issue in the same commit (except, + of course, if one code change fixes all of them). +* Do **not** do cosmetic changes to unrelated code in the same + commit as some feature/bugfix. -Make a pull request on GitHub from your changes in ``MY_BRANCH_NAME``. +Commit messages should follow the following structure:: -After your PR has been accepted and merged, you can :ref:`delete the branch `:: + bpo-42: the spam module is now more spammy. - git branch -D MY_BRANCH_NAME # delete local branch - git push origin -d MY_BRANCH_NAME # delete remote branch + The spam module sporadically came up short on spam. This change + raises the amount of spam in the module by making it more spammy. -.. note:: - You can still upload a patch to bugs.python.org_, but the GitHub pull request - workflow is **strongly** preferred. +The first line or sentence is meant to be a dense, to-the-point explanation +of what the purpose of the commit is. If this is not enough detail for a +commit, a new paragraph(s) can be added to explain in proper depth what has +happened (detail should be good enough that a core developer reading the +commit message understands the justification for the change). .. _cla: diff --git a/setup.rst b/setup.rst index 9aa654aa6..52da9b672 100644 --- a/setup.rst +++ b/setup.rst @@ -34,22 +34,58 @@ installation directions. You may also want to consider a graphical client such as `TortoiseGit `_ or `GitHub Desktop `_. -You may also wish to set up :ref:`your name and email ` -and `an SSH key +Once you installed Git, you should set up +:ref:`your name and email ` and `an SSH key `_ as this will allow you to interact with GitHub without typing a username and password each time you execute a command, such as ``git pull``, ``git push``, or ``git fetch``. On Windows, you should also :ref:`enable autocrlf `. + .. _checkout: Getting the Source Code ----------------------- -In order to get a copy of the source code you should first :ref:`fork the -Python repository on GitHub ` and then :ref:`create a local -clone of your private fork and configure the remotes `. +In order to get a copy of the source code you should :ref:`fork the +Python repository on GitHub `, :ref:`create a local +clone of your personal fork, and configure the remotes `. + +You will only need to execute these steps once: + +1. Go to https://github.com/python/cpython. + +2. Press :guilabel:`Fork` on the top right. + +3. When asked where to fork the repository, choose to fork it to your username. + +4. Your fork will be created at :samp:`https://github.com/{}/cpython`. + +5. Clone your GitHub fork (replace ```` with your username):: + + $ git clone git@github.com:/cpython.git + + (You can use both SSH-based or HTTPS-based URLs.) + +6. Configure an ``upstream`` remote:: + + $ cd cpython + $ git remote add upstream git@github.com:python/cpython.git + +7. Verify that your setup is correct:: + + $ git remote -v + origin git@github.com:/devguide.git (fetch) + origin git@github.com:/devguide.git (push) + upstream git@github.com:python/devguide.git (fetch) + upstream git@github.com:python/devguide.git (push) + +If you did everything correctly, you should now have a copy of the code +in the ``cpython`` dir and two remotes that refer to your own GitHub fork +(``origin``) and the official CPython repository (``upstream``). + +.. XXX move the text below in pullrequest If you want a working copy of an already-released version of Python, i.e., a version in :ref:`maintenance mode `, you can checkout