|
|
@@ -11,18 +11,20 @@ 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"
|
|
|
+ $ git config --global user.name "Your Real Name"
|
|
|
+ $ git config --global user.email "you@email.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.
|
|
|
+changes for Trac ticket #xxxxx. By creating a fully-ready pull request you
|
|
|
+will make the committers' job easier, meaning that your work is more likely to
|
|
|
+be merged into Django.
|
|
|
+
|
|
|
+You could also upload a traditional patch to Trac, but it's less practical for
|
|
|
+reviews.
|
|
|
|
|
|
.. _Git: http://git-scm.com/
|
|
|
.. _GitHub: https://github.com/
|
|
|
@@ -31,14 +33,18 @@ less practical for reviews.
|
|
|
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::
|
|
|
+When you have created your GitHub account, with the nick "github_nick", and
|
|
|
+forked Django's repository, 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::
|
|
|
+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 (that is, tell git
|
|
|
+that the reference Django repository was the source of your fork of it)::
|
|
|
|
|
|
git remote add upstream git@github.com:django/django.git
|
|
|
git fetch upstream
|
|
|
@@ -50,12 +56,15 @@ You can add other remotes similarly, for example::
|
|
|
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::
|
|
|
+When working on a ticket 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::
|
|
|
+The -b flag creates a new branch for you locally. Don't hesitate to create new
|
|
|
+branches even for the smallest things - that's what they are there for.
|
|
|
+
|
|
|
+If instead you were working for a fix on the 1.4 branch, you would do::
|
|
|
|
|
|
git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
|
|
|
|
|
|
@@ -64,7 +73,7 @@ commit them::
|
|
|
|
|
|
git commit
|
|
|
|
|
|
-When writing the commit message, you should follow the :ref:`commit message
|
|
|
+When writing the commit message, 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.
|
|
|
@@ -77,69 +86,77 @@ necessary::
|
|
|
Publishing work
|
|
|
~~~~~~~~~~~~~~~
|
|
|
|
|
|
-You can publish your work on GitHub by just using::
|
|
|
+You can publish your work on GitHub just by doing::
|
|
|
|
|
|
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.
|
|
|
+Note that the above branch is called a "topic branch" in Git parlance. You are
|
|
|
+free to rewrite the history of this branch, by using ``git rebase`` for
|
|
|
+example. Other people shouldn't base their work on such a branch, because
|
|
|
+their clone would become corrupt when you edit commits.
|
|
|
+
|
|
|
+There are also "public branches". These are branches other people are supposed
|
|
|
+to fork, so the history of these branches 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:
|
|
|
+a pull request at GitHub. A good pull request means:
|
|
|
|
|
|
-* Commits with one logical change in each, following the
|
|
|
- :doc:`coding style <coding-style>`.
|
|
|
+* 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.
|
|
|
+* 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.
|
|
|
+* documentation and tests, if needed -- actually tests are always needed,
|
|
|
+ except for documentation changes.
|
|
|
|
|
|
-* The test suite passes and the documentation builds without warnings.
|
|
|
+The test suite must pass and the documentation must build 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".
|
|
|
+related Trac ticket explaining what you've done. In particular you should note
|
|
|
+the environment in which you ran 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.
|
|
|
+Pull requests at GitHub have only two states: open and closed. The committer
|
|
|
+who will deal 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::
|
|
|
+and "Added two more tests" commit.
|
|
|
+
|
|
|
+We do not want to have the entire history of your working process in your
|
|
|
+repository. Your commit "Added two more tests" would be unhelpful noise.
|
|
|
+Instead, we would rather only have one commit containing all your work.
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+Change the second line to "squash" instead. This will keep the
|
|
|
+first commit, and squash the second commit into the first one. Save and quit
|
|
|
+the editor. A second editor window should open, so you can reword the
|
|
|
+commit message for the commit now that it includes both your steps.
|
|
|
|
|
|
You can also use the "edit" option in rebase. This way you can change a single
|
|
|
-commit. For example::
|
|
|
+commit, for example to fix a typo in a docstring::
|
|
|
|
|
|
git rebase -i HEAD~3
|
|
|
# Choose edit, pick, pick for the commits
|
|
|
@@ -148,17 +165,18 @@ commit. For example::
|
|
|
git commit --amend
|
|
|
# reword the commit message if needed
|
|
|
git rebase --continue
|
|
|
- # The second and third commit should be applied.
|
|
|
+ # The second and third commits should be applied.
|
|
|
|
|
|
-If you need to change an already published topic branch at GitHub, you will
|
|
|
-need to force-push the changes::
|
|
|
+If your topic branch is already published at GitHub, for example if you're
|
|
|
+making minor changes to take into account a review, 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.
|
|
|
+commit hashes do not match any more. This is acceptable, as the branch is merely
|
|
|
+a topic branch, and nobody should be basing their work on it.
|
|
|
|
|
|
After upstream has changed
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
@@ -173,16 +191,18 @@ 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
|
|
|
+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.
|
|
|
+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 in with* the changes in the upstream.
|
|
|
+This way your branch will contain only commits related to its topic, which
|
|
|
+makes squashing easier.
|
|
|
|
|
|
After review
|
|
|
------------
|
|
|
@@ -190,31 +210,35 @@ 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::
|
|
|
+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
|
|
|
+In this case, do the changes required by the reviewer. Commit as often as
|
|
|
+necessary. Before publishing the changes, rebase your work. If you added two
|
|
|
+commits, you would run::
|
|
|
|
|
|
- - Fixed whitespace errors in foo/bar
|
|
|
- - Reworded the doc string of the_method()
|
|
|
+ git rebase -i HEAD~2
|
|
|
|
|
|
- # 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.
|
|
|
+Squash the second commit into the first. Write a commit message along the lines of::
|
|
|
+
|
|
|
+ Made changes asked in review by <reviewer>
|
|
|
+
|
|
|
+ - Fixed whitespace errors in foobar
|
|
|
+ - Reworded the docstring of bar()
|
|
|
+
|
|
|
+Finally push your work back to your GitHub repository. Since you didn't touch
|
|
|
+the public commits during the rebase, you should not need to force-push::
|
|
|
+
|
|
|
+ git push origin ticket_xxxxx
|
|
|
+
|
|
|
+Your pull request should now contain the new commit too.
|
|
|
|
|
|
-The committer is likely to squash the review commit into the previous commit
|
|
|
+Note that the committer is likely to squash the review commit into the previous commit
|
|
|
when committing the code.
|
|
|
|
|
|
Summary
|
|
|
-------
|
|
|
|
|
|
-* Work on GitHub if possible.
|
|
|
+* Work on GitHub if you can.
|
|
|
* 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.
|
Aymeric Augustin