Skip to content

Commit

Permalink
Reorganize git commands (python#263)
Browse files Browse the repository at this point in the history 
* Move the minimal configuration instructions.

* Move the remote configuration instructions.

* Move the pushing changes and synching remotes sections.

* First cleanup pass.

* Remove the "Maintaining a repository" section.

* Move the "Reverting a Merged Pull Request" section under "Working with Git".

* Fix incorrect markup.
  • Loading branch information
@ezio-melotti
ezio-melotti authored Sep 7, 2017
1 parent 5657771 commit 90747c5
Show file tree
Hide file tree
Showing 4 changed files with 82 additions and 170 deletions.
157 changes: 12 additions & 145 deletions committing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_
=================
Expand Down Expand Up @@ -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 protected]

``--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 <checkout>` 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 <forking>`, 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/<your-username>/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/<your-username>/cpython (fetch)
origin https://github.com/<your-username>/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
Expand Down Expand Up @@ -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.
55 changes: 54 additions & 1 deletion gitbootcamp.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ relevant to CPython's workflow.

.. contents::

.. _fork-cpython:

Forking CPython GitHub Repository
---------------------------------
Expand All @@ -24,24 +25,61 @@ You'll only need to do this once.

4. Your fork will be created at https://github.com/<username>/cpython.

.. _clone-your-fork:

Cloning The Forked CPython Repository
-------------------------------------

You'll only need to do this once. From your command line::

$ git clone [email protected]:<username>/cpython.git

It is also recommended to configure an ``upstream`` remote::

$ cd cpython
$ git remote add upstream [email protected]: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 [email protected]:<your-username>/devguide.git (fetch)
origin [email protected]:<your-username>/devguide.git (push)
upstream [email protected]:python/devguide.git (fetch)
upstream [email protected]: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 protected]

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
-------------------------------
Expand Down Expand Up @@ -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 <filename>

Commit the files::

$ git commit -m '<message>'


.. _push-changes:

Pushing Changes
---------------
Expand Down
11 changes: 6 additions & 5 deletions pullrequest.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -107,21 +107,22 @@ Here is a quick overview of how you can contribute to CPython on GitHub:

#. :ref:`Get started <setup>` and set up your system

#. Fork `CPython`_ on GitHub (using the Fork button in the upper-right on GitHub)
#. :ref:`Fork CPython <fork-cpython>` (using the Fork button in the
upper-right on GitHub)

#. :ref:`Clone your GitHub fork and add an "upstream" remote <clone-your-fork>`

#. :ref:`Build Python <compiling>` on your system

#. :ref:`Run tests <runtests>` after you have built Python

#. :ref:`Add an "upstream" Remote in Git <remote-configuration>` (using SSH,
or you can `use HTTPS`_)

#. :ref:`Create a Branch in Git <pullrequest-steps>` where you can work on
changes

#. :ref:`Run tests <runtests>` again

#. :ref:`Push commits <committing-push-changes>` to your GitHub repo
#. :ref:`Commit <commit-changes>` and :ref:`push <push-changes>`
changes to your GitHub fork

#. `Create Pull Request`_ on GitHub to merge a branch from your fork

Expand Down
29 changes: 10 additions & 19 deletions setup.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,36 +34,27 @@ installation directions. You may also want to consider a graphical client
such as `TortoiseGit <https://tortoisegit.org/>`_ or
`GitHub Desktop <https://desktop.github.com/>`_.

You may also wish to
`set up an SSH key <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_
You may also wish to set up :ref:`your name and email <set-up-name-email>`
and `an SSH key
<https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_
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 <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 <indevbranch>` 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 <fork-cpython>` and then :ref:`create a local
clone of your private fork and configure the remotes <clone-your-fork>`.

If you want a working copy of an already-released version of Python,
i.e., a version in :ref:`maintenance mode <maintbranch>`, 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.

Expand Down

0 comments on commit 90747c5

Please sign in to comment.