canmove, Confirmed users, Bureaucrats and Sysops emeriti
4,714
edits
Auto-tools/Projects/Mozmill/RepoSetup: Difference between revisions
→Ready for a review
(note about remote tracking branch) |
|||
| (17 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
= Getting Started = | = Getting Started = | ||
* Get a [https://github.com/ | * Get a [https://github.com/ GitHub account] | ||
* Fork the [http://github.com/ | * Fork the [http://github.com/mozilla/mozmill mozilla/mozmill] repo (use the Github UI for this) | ||
* Install [http://git-scm.com/ git] on your system | * Install [http://git-scm.com/ git] on your system | ||
* Clone your fork using your ssh key URL on | * Clone your fork using your ssh key URL on Github: | ||
<pre>git clone git@github.com:<your-github-username>/mozmill.git</pre> | <pre>git clone git@github.com:<your-github-username>/mozmill.git</pre> | ||
* If you don't want to get a | * 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: | ||
<pre>git clone http://github.com/ | <pre>git clone http://github.com/mozilla/mozmill.git</pre> | ||
= Setting up for Development on Master = | = 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: | 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: | ||
<pre>git remote add | <pre>cd mozmill; git remote add mozilla git://github.com/mozilla/mozmill.git</pre> | ||
If you are going to commit to master: | |||
<pre>git remote add mozilla git@github.com:mozilla/mozmill.git</pre> | |||
Here's how to stay up to date with the remote mozautomation repository: | Here's how to stay up to date with the remote mozautomation repository: | ||
<pre> | <pre> | ||
git pull | 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 | |||
git push origin master | |||
</pre> | </pre> | ||
Now you're in sync. Unless you're working on a maintenance release, skip down to "getting stuff done". | 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. | = 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). | 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: | |||
<pre>git | <pre> | ||
git | git fetch mozilla | ||
git branch hotfix-1.5 mozilla/hotfix-1.5 | |||
git checkout hotfix-1.5 | |||
</pre> | |||
Now you're on a local branch called "hotfix-1.5" with the 1.5 code. Use <tt>git checkout</tt> to switch between local branches. | |||
To keep your hotfix-1.5 branch updated with the changes to mozauto's 1.5 branch: | |||
<pre>git pull --rebase mozilla hotfix-1.5</pre> | |||
= Getting Stuff Done = | = 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): | |||
<pre> | <pre> | ||
git | git checkout master // we're doing a fix that will land on mozauto master | ||
git pull mozauto master | git pull --rebase mozauto master // make sure local master is up to date | ||
git | git checkout -b myfeature // create new feature branch based on master | ||
git | // make some changes to some files | ||
git commit -a -m "did some stuff" // commit changes to your local myfeature branch | |||
</pre> | </pre> | ||
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). | 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 | == 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: | |||
<pre> | <pre> | ||
git checkout | 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) | |||
git push origin myfeature // pushes | |||
</pre> | </pre> | ||
| Line 58: | Line 57: | ||
We want to diff your feature branch against the master branch. So ensure your master is up to date and create the diff: | We want to diff your feature branch against the master branch. So ensure your master is up to date and create the diff: | ||
<pre> | <pre> | ||
git checkout myfeature | git checkout myfeature // switch to myfeature branch if not already on it | ||
git | git rebase -i master // Rewrite commits to a single one | ||
git format-patch HEAD^ // Create the patch | |||
</pre> | </pre> | ||
Now, attach | Now, attach the created file to a bug in [http://bugzilla.mozilla.org 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 == | == Ready to Push == | ||
''This only applies if you have commit access to mozautomation'' | ''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 [http://www. | 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 [http://www.gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html] to just the salient commits. You can do that using interactive rebase: | ||
<pre> | <pre> | ||
git checkout myfeature | git checkout myfeature | ||
| Line 72: | Line 72: | ||
</pre> | </pre> | ||
Ok, you've gotten your review, your commits are in good shape, and your commit message is correct, then you're ready to push | 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: | ||
<pre> | <pre> | ||
git checkout master // Switch to master branch | git checkout master // Switch to master branch | ||
git pull --rebase | git pull --rebase mozilla master // Ensure your master is up to date: see below... | ||
git merge myfeature // Merges your commits to the master | git merge myfeature // Merges your commits to the master | ||
git push origin master // Pushes to your fork | git push origin master // Pushes to your fork | ||
git push | git push mozilla master // Pushes to mozilla master | ||
// PARTY! | // PARTY! | ||
</pre> | </pre> | ||
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. | 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 == | == Delete a Feature Branch == | ||
| Line 105: | Line 88: | ||
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": | 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": | ||
<pre> | <pre> | ||
git checkout master // | git checkout master // Move to some other branch | ||
git branch - | git branch -D myfeature // Delete the myfeature branch | ||
</pre> | </pre> | ||
Now, if the branch was pushed to your | Now, if the branch was pushed to your Github repo, we add another step. | ||
<pre> | <pre> | ||
git push origin :myfeature // Removes the branch from github | git push origin :myfeature // Removes the branch from github | ||
</pre> | </pre> | ||
| Line 119: | Line 100: | ||
This is about writing tests for the Mozmill tool itself, not writing Mozmill tests. For writing Mozmill tests, please refer to the [https://developer.mozilla.org/en/Mozmill Mozilla Developer Network pages]. | This is about writing tests for the Mozmill tool itself, not writing Mozmill tests. For writing Mozmill tests, please refer to the [https://developer.mozilla.org/en/Mozmill Mozilla Developer Network pages]. | ||
A test framework for the Mozmill tool itself | A test framework for the Mozmill tool itself has been constructed. See: https://github.com/mozilla/mozmill/tree/master/mutt | ||