Auto-tools/Projects/Mozmill/RepoSetup
Contents
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