diff --git a/committing.rst b/committing.rst index 1989b580bc..1265ff11e2 100644 --- a/committing.rst +++ b/committing.rst @@ -268,23 +268,6 @@ understands the justification for the change). Also, if a non-core developer contributed to the resolution, it is good practice to credit them. -Reverting a Commit ------------------- - -To revert a merged pull request, press the ``Revert`` button at the bottom of -the pull request. It will bring up the page to create a new pull request where -the commit can be reverted. It also creates a new branch on the main CPython -repository. Delete the branch once the pull request has been merged. - -Always include the reason for reverting the commit to help others understand -why it was done. The reason should be included as part of the commit message, -for example:: - - Revert bpo-NNNN: Fix Spam Module (GH-111) - - Reverts python/cpython#111. - Reason: This commit broke the buildbot. - Working with Git_ ================= @@ -313,107 +296,6 @@ into a state you aren't happy with. .. _Git: https://git-scm.com/ -Minimal Configuration ---------------------- - -If you use Git as a committer of patches (your own or others), you should -set up some basic options. Here are the minimal options you need to activate: - -* Your *name* and *email*: these settings defines what will be used when you - commit changes:: - - git config --global user.name "Your Name" - git config --global user.email email@example.org - -``--global`` flag sets configuration options at a global level, if instead you -want to set it at a project level use ``--local``, instead. - -* *Under Windows*, you should also enable the *autocrlf* option, which will - fix any Windows-specific line endings your text editor might insert when you - create or modify versioned files. The public repository has a hook which - will reject all changesets having the wrong line endings, so enabling this - extension on your local computer is in your best interest. - :: - - git config --global core.autocrlf input - - -Remotes Setup -------------- - - -.. _remote-configuration: - -Configuration -''''''''''''' - -There are several possible ways how to set up your git repository. This section -discusses the simplest approach of having a single directory with two remotes, -one pointing to private fork, the other one being the official repository. - -Assuming you have :ref:`cloned the official repository ` here is how -your current setup should look like:: - - $ git remote -v # show remotes - origin https://github.com/python/cpython (fetch) - origin https://github.com/python/cpython (push) - -You can have multiple remotes defined for a single repository, the usual approach -is to have ``origin`` pointing to your :ref:`private fork `, and ``upstream`` -pointing to the official repository. To do so, here are the steps needed to have -that setup:: - - git remote set-url origin https://github.com//cpython - git remote add upstream https://github.com/python/cpython - -After that, your remotes configuration should look like this:: - - $ git remote -v # show remotes - origin https://github.com//cpython (fetch) - origin https://github.com//cpython (push) - upstream https://github.com/python/cpython (fetch) - upstream https://github.com/python/cpython (push) - -At any point in time you can use SSH-based URL instead of HTTPS-based ones. - - -.. _committing-push-changes: - -Pushing changes -''''''''''''''' - -You have two remotes configured (see previous section for setup). Publishing -your changes to any of them is as simple as specifying the name of the remote -upon your push. Assuming I am working on a local branch ``bug1234`` and I want to -push it to my private fork I do:: - - git push origin bug1234 - -Option ``-u|--set-upstream`` creates a remote-tracking branch that tracks what -have been pushed to ``origin``:: - - git push -u origin bug1234 - -That allows to avoid rebasing beyond already pushed commits. -``git status --branch`` and ``git branch --verbose`` remind that the branch(es) -have not pushed commits. - - -Synchronizing remotes -''''''''''''''''''''' - -To synchronize your fork, from the official repository you need to execute following -commands:: - - git fetch upstream # fetch remote changes - git checkout master # checkout your current master branch - git merge upstream/master # merge remote changes into your local master branch - git push origin master # publish changes to your private fork - -The above steps can be executed against any branch you wish to, just replace master -with an appropriate branch name. - - .. _committing-active-branches: Active branches @@ -454,34 +336,19 @@ Developers can apply labels to GitHub pull requests). .. _cherry_picker.py: https://github.com/python/core-workflow/tree/master/cherry_picker -.. _forking: - -Forking repository ------------------- - -Forking a repository on GitHub is as simple as clicking Fork button in the right -upper corner at https://github.com/python/cpython. - +Reverting a Merged Pull Request +------------------------------- -Maintaining a repository ------------------------- +To revert a merged pull request, press the ``Revert`` button at the bottom of +the pull request. It will bring up the page to create a new pull request where +the commit can be reverted. It also creates a new branch on the main CPython +repository. Delete the branch once the pull request has been merged. -The Git object database and other files/directories under ``.git`` require -periodic maintenance and cleanup. For example, commit editing leaves -unreferenced objects (dangling objects, in git terminology) and these -objects should be pruned to avoid collecting cruft in the DB. The -command ``git gc`` is used for maintenance. Git automatically runs -``git gc --auto`` as a part of some commands to do quick maintenance. -Users are recommended to run ``git gc --aggressive`` from time to -time; ``git help gc`` recommends to run it every few hundred -changesets; for CPython it should be something like once a week -(GitHub itself runs the command weekly, so new checkouts do not need to -perform this step). +Always include the reason for reverting the commit to help others understand +why it was done. The reason should be included as part of the commit message, +for example:: -``git gc --aggressive`` not only removes dangling objects, it also -repacks object database into indexed and better optimized pack(s); it -also packs symbolic references (branches and tags). + Revert bpo-NNNN: Fix Spam Module (GH-111) -From time to time run ``git fsck --strict`` to verify integrity of -the database. ``git fsck`` may produce a list of dangling objects; -that's not an error, just a reminder to perform regular maintenance. + Reverts python/cpython#111. + Reason: This commit broke the buildbot. diff --git a/gitbootcamp.rst b/gitbootcamp.rst index bb4482aa58..c0762aaeb9 100644 --- a/gitbootcamp.rst +++ b/gitbootcamp.rst @@ -10,6 +10,7 @@ relevant to CPython's workflow. .. contents:: +.. _fork-cpython: Forking CPython GitHub Repository --------------------------------- @@ -24,6 +25,7 @@ You'll only need to do this once. 4. Your fork will be created at https://github.com//cpython. +.. _clone-your-fork: Cloning The Forked CPython Repository ------------------------------------- @@ -31,17 +33,53 @@ Cloning The Forked CPython Repository You'll only need to do this once. From your command line:: $ git clone git@github.com:/cpython.git + +It is also recommended to configure an ``upstream`` remote:: + $ cd cpython $ git remote add upstream git@github.com:python/cpython.git +You can also use SSH-based or HTTPS-based URLs. Listing the Remote Repositories ------------------------------- -To list the remote repositories that are configured, along with their urls:: +To list the remote repositories that are configured, along with their URLs:: $ git remote -v +You should have two remotes: ``origin`` pointing to your fork, +and ``upstream`` pointing to the official CPython repository:: + + 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) + + +.. _set-up-name-email: + +Setting Up Your Name and Email Address +-------------------------------------- +:: + + $ git config --global user.name "Your Name" + $ git config --global user.email email@example.org + +The ``--global`` flag sets these globally, +``--local`` sets them only for the current project. + +.. _autocrlf: + +Enabling ``autocrlf`` on Windows +-------------------------------- + +The *autocrlf* option will fix automatically any Windows-specific line endings. +This should be enabled on Windows, since the public repository has a hook which +will reject all changesets having the wrong line endings. +:: + + $ git config --global core.autocrlf input Creating and Switching Branches ------------------------------- @@ -139,6 +177,21 @@ To re-apply the last stashed change:: $ git stash pop +.. _commit-changes: + +Committing Changes +------------------ + +Add the files you want to commit:: + + $ git add + +Commit the files:: + + $ git commit -m '' + + +.. _push-changes: Pushing Changes --------------- diff --git a/pullrequest.rst b/pullrequest.rst index e9b352823f..f447b6b1b1 100644 --- a/pullrequest.rst +++ b/pullrequest.rst @@ -107,21 +107,22 @@ Here is a quick overview of how you can contribute to CPython on GitHub: #. :ref:`Get started ` and set up your system -#. Fork `CPython`_ on GitHub (using the Fork button in the upper-right on GitHub) +#. :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 -#. :ref:`Add an "upstream" Remote in Git ` (using SSH, - or you can `use HTTPS`_) - #. :ref:`Create a Branch in Git ` where you can work on changes #. :ref:`Run tests ` again -#. :ref:`Push commits ` to your GitHub repo +#. :ref:`Commit ` and :ref:`push ` + changes to your GitHub fork #. `Create Pull Request`_ on GitHub to merge a branch from your fork diff --git a/setup.rst b/setup.rst index 8e83b8a14d..9aa654aa63 100644 --- a/setup.rst +++ b/setup.rst @@ -34,36 +34,27 @@ installation directions. You may also want to consider a graphical client such as `TortoiseGit `_ or `GitHub Desktop `_. -You may also wish to -`set up an SSH key `_ +You may also wish to 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``. - +``git push``, or ``git fetch``. On Windows, you should also +:ref:`enable autocrlf `. .. _checkout: Getting the Source Code ----------------------- -One should always work from a working copy of the CPython source code. -While it may -be tempting to work from the copy of Python you already have installed on your -machine, it is very likely that you will be working from out-of-date code as -the Python core developers are constantly updating and fixing things in their -:abbr:`VCS (version control system)`. It also means you will have better tool -support through the VCS as it will provide a diff tool, etc. - -To get a working copy of the :ref:`in-development ` branch of -CPython, run:: - - git clone https://github.com/python/cpython +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 `. If you want a working copy of an already-released version of Python, i.e., a version in :ref:`maintenance mode `, you can checkout -a release branch. For instance, to checkout a working copy of Python 3.5, do:: - - git checkout 3.5 +a release branch. For instance, to checkout a working copy of Python 3.5, +do ``git checkout 3.5``. You will need to re-compile CPython when you do such an update.