Auto-tools/Projects/Mozmill/RepoSetup

Getting Started

• Get a github account
• Fork the mozautomation/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:<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/mozautomation/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:

git remote add mozauto git@github.com:mozautomation/mozmill.git

Now you can update from your own fork:

git pull origin master

And you can update from the remote mozautomation repo's master:

git pull mozauto master

And if there are changes that came down from the mozautomation repo, you can push them up to your fork:

git push origin master

Setting up for Development on 1.4.2

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.4.2 code into a local branch:

git checkout -b 1.4.2
git pull mozauto 1.4.2

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

Getting some stuff Done

We recommend doing all your work against master. Then if we need to take that patch on a maintenance branch, we can address that later with your patch from the master tree. So, to work on master, here's what you need to do.

git pull origin master        // Ensures that you're up to date with your fork
git pull mozauto master       // Ensures you're up to date with mozauto
git checkout -b myfeature     // makes branch and switches you to the 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

git checkout master           // Gets you back on the master branch
git push origin myfeature     // pushes your feature branch to github

Finished some pieces of code, push them to github

 
git add <myfile>              // adds your file to the change to be picked up
                              // do this for both new and modified files
git commit -m "some message"  // commits your current change
git push origin myfeature     // pushes your feature branch (and your commits to your github fork)

Ready for a review

git diff -U8 -p > mypatch.diff

Now, attach that patch 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 squash those down 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!

git checkout master              // Switch to master branch
git pull --rebase mozauto 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 mozauto master          // Pushes to mozautomation 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.

Pushing to 1.4.2 (or any maintenance branch)

This only applies to you if you have commit access to mozautomation.

This workflow assumes that you have a patch that you uploaded to bugzilla. I'll assume that you've created that patch against the master and now we're going to backport it to the maintenance branch. Here's how to do that.

git checkout 1.4.2              // Switches to your 1.4.2 branch
git pull --rebase mozauto 1.4.2 // Ensure the 1.4.2 branch is up to date
git checkout -b myfeature1.4.2  // Creates a new branch based on 1.4.2 
patch -p1 <mypatch.diff         // Applies your patch to the 1.4.2 based branch
git add <any changed files>     // Ensures files will be committed
git commit -m "msg"             // Use a good commit message
git checkout 1.4.2              // Switches back to clean 1.4.2 branch
git merge myfeature1.4.2        // Merges your patch into the 1.4.2 branch
git push mozauto 1.4.2          // Pushes the changes to 1.4.2 branch on mozauto
                                // PARTY!

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            // Assuming you created this branch from master
git branch -d myfeature        // Deletes the branch

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 is being constructed. For now, do the best you can by writing a simple piece of JavaScript or Python to test the feature you're adding. You can also write a Mozmill test to test itself for this as well. Add your test to the mozmill/test directory.

We'll update here once we have something more complete.