This section explains how the community can contribute code to Django via pull\nrequests. If you’re interested in how mergers handle\nthem, see Committing code.
\nBelow, we are going to show how to create a GitHub pull request containing the\nchanges for Trac ticket #xxxxx. By creating a fully-ready pull request, you\nwill make the reviewer’s job easier, meaning that your work is more likely to\nbe merged into Django.
\nYou could also upload a traditional patch to Trac, but it’s less practical for\nreviews.
\nDjango uses Git for its source control. You can download Git, but it’s often easier to install with\nyour operating system’s package manager.
\nDjango’s Git repository is hosted on GitHub, and it is recommended\nthat you also work using GitHub.
\nAfter installing Git, the first thing you should do is set up your name and\nemail:
\n$ git config --global user.name "Your Real Name"\n$ git config --global user.email "you@email.com"\nNote that user.name should be your real name, not your GitHub nick. GitHub\nshould know the email you use in the user.email field, as this will be\nused to associate your commits with your GitHub account.
When you have created your GitHub account, with the nick „GitHub_nick”, and\nforked Django’s repository,\ncreate a local copy of your fork:
\ngit clone https://github.com/GitHub_nick/django.git\nThis will create a new directory „django”, containing a clone of your GitHub\nrepository. The rest of the git commands on this page need to be run within the\ncloned directory, so switch to it now:
\ncd django\nYour GitHub repository will be called „origin” in Git.
\nYou should also set up django/django as an „upstream” remote (that is, tell\ngit that the reference Django repository was the source of your fork of it):
git remote add upstream https://github.com/django/django.git\ngit fetch upstream\nYou can add other remotes similarly, for example:
\ngit remote add akaariai https://github.com/akaariai/django.git\nWhen working on a ticket, create a new branch for the work, and base that work\non upstream/main:
git checkout -b ticket_xxxxx upstream/main\nThe -b flag creates a new branch for you locally. Don’t hesitate to create new\nbranches even for the smallest things - that’s what they are there for.
\nIf instead you were working for a fix on the 1.4 branch, you would do:
\ngit checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x\nAssume the work is carried on the ticket_xxxxx branch. Make some changes and\ncommit them:
\ngit commit\nWhen writing the commit message, follow the commit message\nguidelines to ease the work of the merger. If you’re\nuncomfortable with English, try at least to describe precisely what the commit\ndoes.
\nIf you need to do additional work on your branch, commit as often as\nnecessary:
\ngit commit -m 'Added two more tests for edge cases'\nYou can publish your work on GitHub by running:
\ngit push origin ticket_xxxxx\nWhen you go to your GitHub page, you will notice a new branch has been created.
\nIf you are working on a Trac ticket, you should mention in the ticket that\nyour work is available from branch ticket_xxxxx of your GitHub repo. Include a\nlink to your branch.
\nNote that the above branch is called a „topic branch” in Git parlance. You are\nfree to rewrite the history of this branch, by using git rebase for\nexample. Other people shouldn’t base their work on such a branch, because\ntheir clone would become corrupt when you edit commits.
There are also „public branches”. These are branches other people are supposed\nto fork, so the history of these branches should never change. Good examples\nof public branches are the main and stable/A.B.x branches in the\ndjango/django repository.
When you think your work is ready to be pulled into Django, you should create\na pull request at GitHub. A good pull request means:
\ncommits with one logical change in each, following the\ncoding style,
well-formed messages for each commit: a summary line and then paragraphs\nwrapped at 72 characters thereafter – see the committing guidelines for more details,
documentation and tests, if needed – actually tests are always needed,\nexcept for documentation changes.
The test suite must pass and the documentation must build without warnings.
\nOnce you have created your pull request, you should add a comment in the\nrelated Trac ticket explaining what you’ve done. In particular, you should note\nthe environment in which you ran the tests, for instance: „all tests pass\nunder SQLite and MySQL”.
\nPull requests at GitHub have only two states: open and closed. The merger who\nwill deal with your pull request has only two options: merge it or close it.\nFor this reason, it isn’t useful to make a pull request until the code is ready\nfor merging – or sufficiently close that a merger will finish it themselves.
\nIn the example above, you created two commits, the „Fixed ticket_xxxxx” commit\nand „Added two more tests” commit.
\nWe do not want to have the entire history of your working process in your\nrepository. Your commit „Added two more tests” would be unhelpful noise.\nInstead, we would rather only have one commit containing all your work.
\nTo rework the history of your branch you can squash the commits into one by\nusing interactive rebase:
\ngit rebase -i HEAD~2\nThe HEAD~2 above is shorthand for two latest commits. The above command\nwill open an editor showing the two commits, prefixed with the word „pick”.
\nChange „pick” on the second line to „squash” instead. This will keep the\nfirst commit, and squash the second commit into the first one. Save and quit\nthe editor. A second editor window should open, so you can reword the\ncommit message for the commit now that it includes both your steps.
\nYou can also use the „edit” option in rebase. This way you can change a single\ncommit, for example to fix a typo in a docstring:
\ngit rebase -i HEAD~3\n# Choose edit, pick, pick for the commits\n# Now you are able to rework the commit (use git add normally to add changes)\n# When finished, commit work with "--amend" and continue\ngit commit --amend\n# Reword the commit message if needed\ngit rebase --continue\n# The second and third commits should be applied.\nIf your topic branch is already published at GitHub, for example if you’re\nmaking minor changes to take into account a review, you will need to force-push\nthe changes:
\ngit push -f origin ticket_xxxxx\nNote that this will rewrite history of ticket_xxxxx - if you check the commit\nhashes before and after the operation at GitHub you will notice that the commit\nhashes do not match anymore. This is acceptable, as the branch is a topic\nbranch, and nobody should be basing their work on it.
\nWhen upstream (django/django) has changed, you should rebase your work. To\ndo this, use:
git fetch upstream\ngit rebase upstream/main\nThe work is automatically rebased using the branch you forked on, in the\nexample case using upstream/main.
The rebase command removes all your local commits temporarily, applies the\nupstream commits, and then applies your local commits again on the work.
\nIf there are merge conflicts, you will need to resolve them and then use git\nrebase --continue. At any point you can use git rebase --abort to return\nto the original state.
Note that you want to rebase on upstream, not merge the upstream.
\nThe reason for this is that by rebasing, your commits will always be on\ntop of the upstream’s work, not mixed in with the changes in the upstream.\nThis way your branch will contain only commits related to its topic, which\nmakes squashing easier.
\nIt is unusual to get any non-trivial amount of code into core without changes\nrequested by reviewers. In this case, it is often a good idea to add the\nchanges as one incremental commit to your work. This allows the reviewer to\neasily check what changes you have done.
\nIn this case, do the changes required by the reviewer. Commit as often as\nnecessary. Before publishing the changes, rebase your work. If you added two\ncommits, you would run:
\ngit rebase -i HEAD~2\nSquash the second commit into the first. Write a commit message along the lines\nof:
\nMade changes asked in review by <reviewer>\n\n- Fixed whitespace errors in foobar\n- Reworded the docstring of bar()\nFinally, push your work back to your GitHub repository. Since you didn’t touch\nthe public commits during the rebase, you should not need to force-push:
\ngit push origin ticket_xxxxx\nYour pull request should now contain the new commit too.
\nNote that the merger is likely to squash the review commit into the previous\ncommit when committing the code.
\nOne of the ways that developers can contribute to Django is by reviewing\npatches. Those patches will typically exist as pull requests on GitHub and\ncan be easily integrated into your local repository:
\ngit checkout -b pull_xxxxx upstream/main\ncurl -L https://github.com/django/django/pull/xxxxx.patch | git am\nThis will create a new branch and then apply the changes from the pull request\nto it. At this point you can run the tests or do anything else you need to\ndo to investigate the quality of the patch.
\nFor more detail on working with pull requests see the\nguidelines for mergers.
\nWork 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.
When doing fixes to your work, use git rebase -i to squash the commits.
When upstream has changed, do git fetch upstream; git rebase.