After you've written your code, the next thing to do is to make a patch! This page will show exactly what changes you made to Bugzilla or its documentation, in a format that we can review and integrate into our codebase.

We also call patches "diffs", because one program used for making patches is called "diff”.

Using git

We are transitioning to git for our source control. Basic usage is very similar to bzr, but there are different concepts and workflows. This is the preferred way of making patches.

Git is very powerful, but anything beyond simple use is greatly aided by an understanding of the whole system. One of the best references is the book Pro Git, which is available for free in its entirety.

The following sections outline some simple workflows; for further details, see the Pro Git book or any of the numerous tutorials and references available online.

The Simple Way: Local uncommitted changes

After cloning the Bugzilla repo and switching to your desired branch, the simplest way to generate a diff is to just make local modifications and use git diff in that branch. This way should only be used if you’re making simple modifications to a couple files and only working on one patch at a time.

If you’ve only modified or removed existing files, then this is all you need:

git diff > patch.diff

This will not catch any new files, since git doesn’t know if you really wanted to add them or if they are just left over from something else, e.g. building. If you want new files included in your patch, then you need to run git add on them. However, in this case, you’ll also have to run git add on any modified files and git rm on any deleted files. This is because once you’ve "staged" changes to be committed (added your new files), you have to tell git about any other changes you want to commit as well. Finally, you’ll have to add --cached to the git diff command. See the chapter of Pro Git on recording changes to the git repository for more details.

You can then upload "patch.diff" as your patch.

The Better Way: Local development branches

If you are intending to do any complicated changes, or if you want to work on more than one patch at a time, or if you just want to do things the typical git way, you’re going to want to create local branches for your work.

After cloning, change to the branch you want to base your work on. Create and switch to a new, local branch by running

git checkout -b <branch_name>

Replace branch_name by something descriptive, e.g. bug-123456 or fix-headers. You might want to include the base branch name as well, particularly if you are doing the same fix to multiple branches.

At this point, you can add, modify, and remove files and commit as often as you like. Because git branches are cheap and easy to throw away, you don't need to be careful about crafting one tidy commit. Even if you have commit permissions and will be pushing your changes to the main git repository yourself, you can still squash commits together later via git rebase before merging into the base branch.

Once you have completed your work, make sure all your changes are committed, then run

git diff <base_branch> > patch.diff

Replace base_branch by the name of the branch off of which your local branch is based, e.g. master, 4.4, 4.2, etc. This will produce a diff of all changes you committed since you branched; upload "patch.diff" as your patch.

You can even "rebase" your local branch to update it with changes that have been done upstream to your base branch by other developers--or even by yourself in another branch. This is out of scope for this simple tutorial, but see the chapter in Pro Git on branching for lots more info, including details on standard git work flows.

Using Bzr

If you checked Bugzilla out of bzr, then you can make patches using bzr.

The Simple Way: bzr diff

The simplest way to make a patch from your current bzr checkout is like this:

bzr diff > patch.diff

And that's it. Then you can upload "patch.diff" as your patch.

If Your Patch Contains Renames: bzr bundle

If your patch contains renames, then you have to use the bzr bundle command to produce your patch. To create a bundle:

1. first you have to locally commit your changes:

   bzr commit --local -m 235423

   There "235423" was the id of the bug I was working on. That's just a fake "commit message" for this patch, it doesn't really matter what I put there.
2. Then create the bundle:

   bzr bundle bzr://bzr.mozilla.org/bugzilla/trunk > patch.bundle

   There, "bzr://bzr.mozilla.org/bugzilla/trunk" is the branch that I'm creating this bundle against. The bundle will, in most cases, only work against that branch.

Then you can attach the bundle just like a normal patch. When you upload it, note that it's a bundle in its description. For example, you might call it "v1 (bundle)".

Applying Bundles

If you have a bundle and you want to apply it to your local installation, you can do it like this:

1. Apply the bundle:

   bzr merge path/to/patch.bundle

2. Remove the fake "commits" that were created while creating the bundle:

   bzr revert --forget-merges

And now you have a checkout with the bundle applied, but without any of the "commits" involved in the bundle.

Moving, Adding, and Deleting Files

Before you make your patch, if you have added, moved, or renamed files, you will have to run certain commands so that those files will show up in your patch.

• If you have added files, you can use bzr add to add them:

  bzr add ''path/to/file''

  Doing bzr add on a directory will add that directory and all files in it. Doing bzr add all by itself, with no arguments, will add every unknown file in your checkout.
• If you have removed files, you don't have to do anything to make them disappear from your patch. However, if you want, you can use bzr rm to remove directories or files and also explicitly notify bzr that they're gone.
• To rename a file, use bzr mv. If you've already renamed a file and you just want bzr to know that you renamed it, you can use bzr mv --after. (Or sometimes, just typing bzr mv --auto all by itself will have bzr automatically "figure out" if you've moved a file.)

Using CVS

Before Bugzilla used Bazaar, it used CVS, and if you installed Bugzilla from the tarball, it's set up so that you can make diffs against CVS.

1. Change to your Bugzilla directory:

 cd /var/www/html/bugzilla

2. Make the patch by doing:

 cvs diff -Nu > patch.diff

3. You now have a file called patch.diff! It includes all your changes to Bugzilla, but it doesn't include any brand-new files that you added. You can add them to the patch by doing:

 diff -Nu /dev/null new-file-name >> patch.diff

Where new-file-name is the name of the file you added.

Alternately, you can also add files to your patch by using the "cvsdo" program on *nix or cvsdo.pl on Windows. Before you do the "cvs diff" in step 2 above, do:

 cvsdo add new-file-name

(Except on Windows, that would be "cvsdo.pl" or "perl.exe cvsdo.pl" instead of just "cvsdo".)

Using diff

Sometimes, for various reasons, you can't use git, bzr, or CVS. In this case, you can get the difference between two Bugzilla directories, one which contains the base Bugzilla, and one which contains your modified Bugzilla.

Here's how to use diff to make a patch:

1. Change to your Bugzilla directory:

 cd /var/www/html/bugzilla

2. Now, Bugzilla contains lots of things that you don't want to diff, like the localconfig file and the data/ directory. So you want to exclude all of those from your diff. Here's a command that will do that:

 diff -Nru --exclude=data --exclude='*.orig' --exclude=CVS --exclude=localconfig --exclude=.bzr --exclude=.htaccess --exclude='.#*' --exclude='*.rej' old/ new/ > patch.diff

Where old/ is the base Bugzilla before your modifications, and new/ is the Bugzilla that you modified.

3. Your patch is now in the file patch.diff.

If you make your patch this way, note that you made it this way when you attach it. (It makes a difference for the reviewer reading it and applying it.)