From c5b768e97e3705e68f95b84294627b4e52278d52 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 6 Sep 2017 01:10:39 +0300 Subject: [PATCH 1/7] Move the minimal configuration instructions. --- committing.rst | 24 ------------------------ gitbootcamp.rst | 23 +++++++++++++++++++++++ setup.rst | 8 ++++---- 3 files changed, 27 insertions(+), 28 deletions(-) diff --git a/committing.rst b/committing.rst index 1989b580b..5f5dc35f5 100644 --- a/committing.rst +++ b/committing.rst @@ -313,30 +313,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 ------------- diff --git a/gitbootcamp.rst b/gitbootcamp.rst index bb4482aa5..ef775712f 100644 --- a/gitbootcamp.rst +++ b/gitbootcamp.rst @@ -42,6 +42,29 @@ To list the remote repositories that are configured, along with their urls:: $ git remote -v +.. _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 ------------------------------- diff --git a/setup.rst b/setup.rst index 8e83b8a14..7cb8b5a48 100644 --- a/setup.rst +++ b/setup.rst @@ -34,12 +34,12 @@ 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 :ref:`set up 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 on Windows `. .. _checkout: From c507009b1d4f56b46915f4e1a6f626573d1d4f01 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 6 Sep 2017 02:32:46 +0300 Subject: [PATCH 2/7] Move the remote configuration instructions. --- committing.rst | 35 ----------------------------------- gitbootcamp.rst | 17 ++++++++++++++++- setup.rst | 20 +++++--------------- 3 files changed, 21 insertions(+), 51 deletions(-) diff --git a/committing.rst b/committing.rst index 5f5dc35f5..13873c4d8 100644 --- a/committing.rst +++ b/committing.rst @@ -318,41 +318,6 @@ 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 diff --git a/gitbootcamp.rst b/gitbootcamp.rst index ef775712f..530339434 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,30 @@ 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 diff --git a/setup.rst b/setup.rst index 7cb8b5a48..5af903662 100644 --- a/setup.rst +++ b/setup.rst @@ -46,24 +46,14 @@ and password each time you execute a command, such as ``git pull``, 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. From cafd72bb645488088103e2dad101a0d713b26019 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 6 Sep 2017 17:20:45 +0300 Subject: [PATCH 3/7] Move the pushing changes and synching remotes sections. --- committing.rst | 37 ------------------------------------- gitbootcamp.rst | 15 +++++++++++++++ pullrequest.rst | 11 ++++++----- 3 files changed, 21 insertions(+), 42 deletions(-) diff --git a/committing.rst b/committing.rst index 13873c4d8..3b9d4f6f2 100644 --- a/committing.rst +++ b/committing.rst @@ -318,43 +318,6 @@ Remotes Setup ------------- -.. _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 diff --git a/gitbootcamp.rst b/gitbootcamp.rst index 530339434..f8dbd60e4 100644 --- a/gitbootcamp.rst +++ b/gitbootcamp.rst @@ -177,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 e9b352823..f447b6b1b 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 From 055d15579d1015e7220b3f823f01a1348c338b57 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 6 Sep 2017 21:03:05 +0300 Subject: [PATCH 4/7] First cleanup pass. --- committing.rst | 14 -------------- setup.rst | 7 ++++--- 2 files changed, 4 insertions(+), 17 deletions(-) diff --git a/committing.rst b/committing.rst index 3b9d4f6f2..e00dff546 100644 --- a/committing.rst +++ b/committing.rst @@ -313,11 +313,6 @@ into a state you aren't happy with. .. _Git: https://git-scm.com/ - -Remotes Setup -------------- - - .. _committing-active-branches: Active branches @@ -358,15 +353,6 @@ 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. - - Maintaining a repository ------------------------ diff --git a/setup.rst b/setup.rst index 5af903662..9aa654aa6 100644 --- a/setup.rst +++ b/setup.rst @@ -34,12 +34,13 @@ installation directions. You may also want to consider a graphical client such as `TortoiseGit `_ or `GitHub Desktop `_. -You may also wish to :ref:`set up your name and email ` and -`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``. On Windows, you should also -:ref:`enable autocrlf on Windows `. +:ref:`enable autocrlf `. .. _checkout: From ae26a039940caee416efc72e33d56130720dfbb9 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 6 Sep 2017 21:12:03 +0300 Subject: [PATCH 5/7] Remove the "Maintaining a repository" section. --- committing.rst | 24 ------------------------ 1 file changed, 24 deletions(-) diff --git a/committing.rst b/committing.rst index e00dff546..498297c52 100644 --- a/committing.rst +++ b/committing.rst @@ -351,27 +351,3 @@ Once the backport pull request has been created, remove the Developers can apply labels to GitHub pull requests). .. _cherry_picker.py: https://github.com/python/core-workflow/tree/master/cherry_picker - - -Maintaining a repository ------------------------- - -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). - -``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). - -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. From b4153d1553142b86bf084617a6e832b5496d8f45 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 6 Sep 2017 21:25:37 +0300 Subject: [PATCH 6/7] Move the "Reverting a Merged Pull Request" section under "Working with Git". --- committing.rst | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/committing.rst b/committing.rst index 498297c52..1265ff11e 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_ ================= @@ -351,3 +334,21 @@ Once the backport pull request has been created, remove the Developers can apply labels to GitHub pull requests). .. _cherry_picker.py: https://github.com/python/core-workflow/tree/master/cherry_picker + + +Reverting a Merged Pull Request +------------------------------- + +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. From a3c6133bd4f3d981285e1930bfd33426b4e99f64 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Thu, 7 Sep 2017 02:26:39 +0300 Subject: [PATCH 7/7] Fix incorrect markup. --- gitbootcamp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gitbootcamp.rst b/gitbootcamp.rst index f8dbd60e4..c0762aaeb 100644 --- a/gitbootcamp.rst +++ b/gitbootcamp.rst @@ -34,7 +34,7 @@ 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:: +It is also recommended to configure an ``upstream`` remote:: $ cd cpython $ git remote add upstream git@github.com:python/cpython.git