mirror of https://github.com/django/django.git
223 lines
8.7 KiB
Plaintext
223 lines
8.7 KiB
Plaintext
Working with Git and GitHub
|
|
===========================
|
|
|
|
Django uses `Git`_ for its source control. You can `download
|
|
<http://git-scm.com/download>`_ Git, but it's often easier to install with
|
|
your operating system's package manager.
|
|
|
|
Django's `Git repository`_ is hosted on `GitHub`_, and it is recommended
|
|
that you also work using GitHub.
|
|
|
|
After installing Git the first thing you should do is setup your name and
|
|
email::
|
|
|
|
$ git config --global user.name "Firstname Lastname"
|
|
$ git config --global user.email "your_email@youremail.com"
|
|
|
|
Note that ``user.name`` should be your real name, not your GitHub nick. GitHub
|
|
should know the email you use in the ``user.email`` field, as this will be
|
|
used to associate your commits with your GitHub account.
|
|
|
|
Now we are going to show how to create a GitHub pull request containing the
|
|
changes for Trac ticket #xxxxx. By creating a fully ready pull request you
|
|
will make the committers' job easier, and thus your work is more likely to be
|
|
merged into Django. You can also upload a traditional patch to Trac, but it's
|
|
less practical for reviews.
|
|
|
|
.. _Git: http://git-scm.com/
|
|
.. _GitHub: https://github.com/
|
|
.. _Git repository: https://github.com/django/django/
|
|
|
|
Setting up local repository
|
|
---------------------------
|
|
|
|
When you have created a GitHub account, with the nick "github_nick", and
|
|
forked Django's repository, you should create a local copy of your fork::
|
|
|
|
git clone git@github.com:github_nick/django.git
|
|
|
|
This will create a new directory "django" containing a clone of your GitHub
|
|
repository. Your GitHub repository will be called "origin" in Git. You should
|
|
also setup django/django as an "upstream" remote::
|
|
|
|
git remote add upstream git@github.com:django/django.git
|
|
git fetch upstream
|
|
|
|
You can add other remotes similarly, for example::
|
|
|
|
git remote add akaariai git@github.com:akaariai/django.git
|
|
|
|
Working on a ticket
|
|
-------------------
|
|
|
|
When working on a ticket you will almost always want to create a new branch
|
|
for the work, and base that work on upstream/master::
|
|
|
|
git checkout -b ticket_xxxxx upstream/master
|
|
|
|
If you are working for a fix on the 1.4 branch, you would instead do::
|
|
|
|
git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
|
|
|
|
Assume the work is carried on ticket_xxxxx branch. Make some changes and
|
|
commit them::
|
|
|
|
git commit
|
|
|
|
When writing the commit message, you should follow the :ref:`commit message
|
|
guidelines <committing-guidlines>` to ease the work of the committer. If
|
|
you're uncomfortable with English, try at least to describe precisely what the
|
|
commit does.
|
|
|
|
If you need to do additional work on your branch, commit as often as
|
|
necessary::
|
|
|
|
git commit -m 'Added two more tests for edge cases'
|
|
|
|
Publishing work
|
|
~~~~~~~~~~~~~~~
|
|
|
|
You can publish your work on GitHub by just using::
|
|
|
|
git push origin ticket_xxxxx
|
|
|
|
When you go to your GitHub page you will notice a new branch has been created.
|
|
If you are working on a Trac ticket, you should mention in the ticket that
|
|
your work is available from branch ticket_xxxxx of your github repo. Include a
|
|
link to your branch.
|
|
|
|
Note that the above branch is called a "topic branch" in Git parlance. This
|
|
means that other people should not base their work on your branch. In
|
|
particular this means you are free to rewrite the history of this branch (by
|
|
using ``git rebase`` for example). There are also "public branches". These are
|
|
branches other people are supposed to fork, and thus their history should
|
|
never change. Good examples of public branches are the ``master`` and
|
|
``stable/A.B.x`` branches in the django/django repository.
|
|
|
|
When you think your work is ready to be pulled into Django, you should create
|
|
a pull request at GitHub. A good pull request contains:
|
|
|
|
* Commits with one logical change in each, following the
|
|
:doc:`coding style <coding-style>`.
|
|
|
|
* Well formed messages for each commit: a summary line and then paragraphs
|
|
wrapped at 72 characters thereafter. See the :ref:`committing guidelines
|
|
<committing-guidlines>` for more details.
|
|
|
|
* Documentation and tests, if needed. Actually tests are always needed, except
|
|
for documentation changes.
|
|
|
|
* The test suite passes and the documentation builds without warnings.
|
|
|
|
Once you have created your pull request, you should add a comment in the
|
|
related Trac ticket explaining what you've done. In particular you should tell
|
|
in which environment you've run the tests, for instance: "all tests pass under
|
|
SQLite and MySQL".
|
|
|
|
Your pull request should be ready for merging into Django. Pull requests at
|
|
GitHub have only two states: open and closed. The committers who deals with
|
|
your pull request has only two options: merge it or close it. For this reason,
|
|
it isn't useful to make a pull request until the code is ready for merging --
|
|
or sufficiently close that a committer will finish it himself.
|
|
|
|
Rebasing branches
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
In the example above you created two commits, the "Fixed ticket_xxxxx" commit
|
|
and "Added two more tests" commit. We do not want to have the "Added two more
|
|
tests" commit in the Django's repository as it would just be useless noise.
|
|
Instead, we would like to only have one commit. To rework the history of your
|
|
branch you can squash the commits into one by using interactive rebase::
|
|
|
|
git rebase -i HEAD~2
|
|
|
|
The HEAD~2 above is shorthand for two latest commits. The above command
|
|
will open an editor showing the two commits, prefixed with the word "pick".
|
|
You should change the second line to "squash" instead. This will keep the
|
|
first commit, and squash the second commit to the first one. Save and quit
|
|
the editor. A second editor window should open. Here you can reword the
|
|
commit message for the commit.
|
|
|
|
You can also use the "edit" option in rebase. This way you can change a single
|
|
commit. For example::
|
|
|
|
git rebase -i HEAD~3
|
|
# Choose edit, pick, pick for the commits
|
|
# Now you are able to rework the commit (use git add normally to add changes)
|
|
# When finished, commit work with "--amend" and continue
|
|
git commit --amend
|
|
# reword the commit message if needed
|
|
git rebase --continue
|
|
# The second and third commit should be applied.
|
|
|
|
If you need to change an already published topic branch at GitHub, you will
|
|
need to force-push the changes::
|
|
|
|
git push -f origin ticket_xxxxx
|
|
|
|
Note that this will rewrite history of ticket_xxxxx - if you check the commit
|
|
hashes before and after the operation at GitHub you will notice that the
|
|
commit hashes do not match any more. This is acceptable, as the branch is topic
|
|
branch, and nobody should be basing their work on this branch.
|
|
|
|
After upstream has changed
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When upstream (django/django) has changed, you should rebase your work. To
|
|
do this, use::
|
|
|
|
git fetch upstream
|
|
git rebase
|
|
|
|
The work is automatically rebased using the branch you forked on, in the
|
|
example case using upstream/master.
|
|
|
|
The rebase command removes all your local commits temporarily, applies the
|
|
upstream commits, and then applies your local commits again on the work. If
|
|
there are merge conflicts you will need to resolve them and then use ``git
|
|
rebase --continue``. At any point you can use ``git rebase --abort`` to return
|
|
to the original state.
|
|
|
|
Note that you want to rebase on upstream, not merge the upstream. The reason
|
|
for this is that by rebasing, your commits will always be on top of the
|
|
upstream's work, not mixed with the changes in the upstream. This way your
|
|
branch only contains commits related to its topic, and this makes squashing
|
|
easier.
|
|
|
|
After review
|
|
------------
|
|
|
|
It is unusual to get any non-trivial amount of code into core without changes
|
|
requested by reviewers. In this case, it is often a good idea to add the
|
|
changes as one incremental commit to your work. This allows the reviewer to
|
|
easily check what changes you have done::
|
|
|
|
# Do changes required by the reviewer, commit often.
|
|
# Before publishing the changes, rebase your work. Assume you added two
|
|
# commits to the work.
|
|
git rebase -i HEAD~2
|
|
# squash the second commit into the first, write a commit message something
|
|
# like this:
|
|
Made changes asked in review by the_reviewer
|
|
|
|
- Fixed whitespace errors in foo/bar
|
|
- Reworded the doc string of the_method()
|
|
|
|
# Push your work back to your github repo, there should not be any need
|
|
# for force (-f) push, as you didn't touch the public commits in the rebase.
|
|
git push origin ticket_xxxxx
|
|
# Check your pull request, it should now contain the new commit, too.
|
|
|
|
The committer is likely to squash the review commit into the previous commit
|
|
when committing the code.
|
|
|
|
Summary
|
|
-------
|
|
|
|
* Work on GitHub if possible.
|
|
* Announce your work on the Trac ticket by linking to your GitHub branch.
|
|
* When you have something ready, make a pull request.
|
|
* Make your pull requests as good as you can.
|
|
* When doing fixes to your work, use ``git rebase -i`` to squash the commits.
|
|
* When upstream has changed, do ``git fetch upstream; git rebase``.
|