Publishing work¶

You can publish your work on GitHub by running:

gitpushoriginticket_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 thatyour work is available from branch ticket_xxxxx of your GitHub repo. Include alink to your branch.

Note that the above branch is called a “topic branch” in Git parlance. You arefree to rewrite the history of this branch, by usinggitrebase forexample. Other people shouldn’t base their work on such a branch, becausetheir clone would become corrupt when you edit commits.

There are also “public branches”. These are branches other people are supposedto fork, so the history of these branches should never change. Good examplesof public branches are themain andstable/A.B.x branches in thedjango/django repository.

When you think your work is ready to be pulled into Django, you should createa pull request at GitHub. A good pull request means:

• commits with one logical change in each, following thecoding style,

• well-formed messages for each commit: a summary line and then paragraphswrapped at 72 characters thereafter – see thecommitting guidelines for more details,

• documentation and tests, if needed – actually tests are always needed,except for documentation changes.

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 therelated Trac ticket explaining what you’ve done. In particular, you should notethe environment in which you ran the tests, for instance: “all tests passunder SQLite and MySQL”.

Pull requests at GitHub have only two states: open and closed. The merger whowill 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 readyfor merging – or sufficiently close that a merger will finish it themselves.

Rebasing branches¶

In the example above, you created two commits, the “Fixed ticket_xxxxx” commitand “Added two more tests” commit.

We do not want to have the entire history of your working process in yourrepository. 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 byusing interactive rebase:

gitrebase-iHEAD~2

The HEAD~2 above is shorthand for two latest commits. The above commandwill open an editor showing the two commits, prefixed with the word “pick”.

Change “pick” on the second line to “squash” instead. This will keep thefirst commit, and squash the second commit into the first one. Save and quitthe editor. A second editor window should open, so you can reword thecommit 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 singlecommit, for example to fix a typo in a docstring:

gitrebase-iHEAD~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 continuegitcommit--amend# Reword the commit message if neededgitrebase--continue# The second and third commits should be applied.

If your topic branch is already published at GitHub, for example if you’remaking minor changes to take into account a review, you will need to force-pushthe changes:

gitpush-foriginticket_xxxxx

Note that this will rewrite history of ticket_xxxxx - if you check the commithashes before and after the operation at GitHub you will notice that the commithashes do not match anymore. This is acceptable, as the branch is a topicbranch, and nobody should be basing their work on it.

After upstream has changed¶

When upstream (django/django) has changed, you should rebase your work. Todo this, use:

gitfetchupstreamgitrebaseupstream/main

The work is automatically rebased using the branch you forked on, in theexample case usingupstream/main.

The rebase command removes all your local commits temporarily, applies theupstream commits, and then applies your local commits again on the work.

If there are merge conflicts, you will need to resolve them and then usegitrebase--continue. At any point you can usegitrebase--abort to returnto the original state.

Note that you want torebase on upstream, notmerge the upstream.

The reason for this is that by rebasing, your commits will always beontop of the upstream’s work, notmixed in with the changes in the upstream.This way your branch will contain only commits related to its topic, whichmakes squashing easier.

After review¶

It is unusual to get any non-trivial amount of code into core without changesrequested by reviewers. In this case, it is often a good idea to add thechanges as one incremental commit to your work. This allows the reviewer toeasily check what changes you have done.

In this case, do the changes required by the reviewer. Commit as often asnecessary. Before publishing the changes, rebase your work. If you added twocommits, you would run:

gitrebase-iHEAD~2

Squash the second commit into the first. Write a commit message along the linesof:

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 touchthe public commits during the rebase, you should not need to force-push:

gitpushoriginticket_xxxxx

Your pull request should now contain the new commit too.

Note that the merger is likely to squash the review commit into the previouscommit when committing the code.