Auto-tools/Projects/Mozmill/RepoSetup

Getting Started

• Get a GitHub account
• Fork the mozilla/mozmill repo (use the Github UI for this)
• Install git on your system
• Clone your fork using your ssh key URL on Github:

git clone git@github.com:<your-github-username>/mozmill.git

• If you don't want to get a Github account, you can still clone the repository, but you won't be able to push upstream or issue pull requests:

git clone http://github.com/mozilla/mozmill.git

Setting up for Development on Master

Master is where the next version of Mozmill comes from. To get ready to work here, you'll need to be able to pull in changes from the remote mozautomation repo. To set that up, you add it as a remote repo:

cd mozmill; git remote add mozilla git://github.com/mozilla/mozmill.git

If you are going to commit to master:

git remote add mozilla git@github.com:mozilla/mozmill.git

Here's how to stay up to date with the remote mozautomation repository:

git pull --rebase mozilla master   # Pulls changes from mozilla to your local machine
git push origin master             # Pushes any changes from mozilla to your Github fork

Now you're in sync. Unless you're working on a maintenance release, skip down to "getting stuff done".

Setting up for Development on 1.5

For work on a maintenance release of Mozmill, we'll use the maintenance release branch. Work for the next major version of Mozmill will be done against the "master" branch, which is already set up. Here's how to set up the maintenance branch on your system (Assuming you've already added mozautomation as a remote repository). Pull the 1.5 code into a local branch:

git fetch mozilla
git branch hotfix-1.5 mozilla/hotfix-1.5
git checkout hotfix-1.5

Now you're on a local branch called "hotfix-1.5" with the 1.5 code. Use git checkout to switch between local branches.

To keep your hotfix-1.5 branch updated with the changes to mozauto's 1.5 branch:

git pull --rebase mozilla hotfix-1.5

Getting Stuff Done

If you're doing a fix to the maintenance branch then check out that branch (e.g. hotfix-1.5.1). If you're doing a fix to master then checkout master. Create a new, temporary branch off of that branch to do your work in (with the example of master):

git checkout master               // we're doing a fix that will land on mozauto master
git pull --rebase mozauto master  // make sure local master is up to date
git checkout -b myfeature         // create new feature branch based on master
// make some changes to some files
git commit -a -m "did some stuff" // commit changes to your local myfeature branch

This is important because it keeps your "master" branch clean. If you use master ONLY as a area for merging upstream to your fork and mozauto, you'll keep things simple and you will have very few (if any) merge conflicts. So, that's why we recommend doing all feature/bugfix work in a branch. You can optionally push that branch up to your github fork as well (that's recommended, then your code doesn't just live on your own machine).

Push a Feature branch to Github

If you want give people a link to your new feature or show someone your code, you can push your local changes to your remote fork on Github so that it appears in that UI:

git checkout myfeature        // switch to feature branch if not already on it
git push origin myfeature     // pushes feature branch to your remote (fork on github)

Ready for a review

We want to diff your feature branch against the master branch. So ensure your master is up to date and create the diff:

git checkout myfeature   // switch to myfeature branch if not already on it
git rebase -i master     // Rewrite commits to a single one
git format-patch HEAD^   // Create the patch

Now, attach the created file to a bug in Bugzilla for review. Don't forget to set the "Review" flag to "?" and add one of the Mozmill module owners in the text box to the right. When in doubt, put in :ctalbert.

Ready to Push

This only applies if you have commit access to mozautomation

Once you have gotten review, it's time to get things ready to land. First, you may have many commits in your patch. We really encourage you to [1] to just the salient commits. You can do that using interactive rebase:

git checkout myfeature
git rebase -i master

Ok, you've gotten your review, your commits are in good shape, and your commit message is correct, then you're ready to push, let's say you want to push to mozilla/master:

git checkout master              // Switch to master branch
git pull --rebase mozilla master // Ensure your master is up to date: see below...
git merge myfeature              // Merges your commits to the master
git push origin master           // Pushes to your fork
git push mozilla master          // Pushes to mozilla master
                                 // PARTY!

You only need to do pull --rebase if your main master branch is NOT clean. If you have changes on master then this will ensure those changes are applied properly with changes coming downstream from the mozauto master. If the master branch is clean, doing pull --rebase doesn't hurt anything, so it's the recommended step.

Delete a Feature Branch

Once you've checked something in, you probably don't want that feature branch cluttering things up on github. There are two ways to delete a branch. If the branch exists locally, you use one way, if the branch was pushed to your github fork, you use another. Here they are:

To delete a local branch, you must switch to the main branch that the local branch was created from. If the branch was created for a feature on the master, then switch to master. If the branch was created for a feature on a maintenance branch, switch to that maintenance branch. Failure to do this will give you a "branch is unmerged warning":

git checkout master            // Move to some other branch
git branch -D myfeature        // Delete the myfeature branch

Now, if the branch was pushed to your Github repo, we add another step.

git push origin :myfeature     // Removes the branch from github

Writing a Test

This is about writing tests for the Mozmill tool itself, not writing Mozmill tests. For writing Mozmill tests, please refer to the Mozilla Developer Network pages.

A test framework for the Mozmill tool itself has been constructed. See: https://github.com/mozilla/mozmill/tree/master/mutt