Confirm
656
edits
Changes
→4. Learn the Webmaker Development Workflow
Every project has its own way of working, and we're no exception. This guide will help you navigate our development workflow so you can be successful as a new contributor.
===1. Get a bug Filed and Assigned to you===
Fixing bugs or adding new features begins in Bugzilla. Whatever you are going to work on, you need to have a bug. Bugs in Bugzilla don't just mean something is broken. A bug is a unit of work, and that might mean fixing a problem in code, but could also mean adding something new, configuring a system differently, setting up an account for someone, etc.
If there isn't a bug filed for the work you'll be doing, you should [https://bugzilla.mozilla.org/enter_bug.cgi?product=Webmaker file a new one]. If you're not sure which component it belongs in, you can use '''General''', and someone will help you move it to the right place.
Once a bug exists, you need to get it assigned to you. This is important because it lets other people in the community know that someone is already working on this. When you create a new Bugzilla account, you won't have privileges yet to assign bugs to yourself. However, if you ask on irc or the the webmaker-dev list, someone will gladly help you out.
===2. Fix the bug and create a Pull Request===
All Webmaker code is in github. You'll need intermediate level understanding of git and github to work on Webmaker, and if you ever get stuck, make sure you ask for help. There are also many good resources online for learning more about git, for example the [http://progit.org/book/ Pro Git, online book].
A typical workflow looks like this:
# Fork the appropriate repo into your own github account
# Clone your fork locally: <code>git clone --recursive {url to your github repo}</code>. NOTE: many Webmaker repos have submodules, so it's wise to clone recursively.
# Add Mozilla's repo as an upstream remote, so you can stay in sync: <code>git remote add upstream {url to Mozilla's github repo}</code>. NOTE: you can call it anything you like, but '''upstream''' is a common convention.
# Create a new branch off master, using the bug number as the name: <code>git checkout -b bug12345</code>
# Work on the code, committing as you go. Don't worry about keeping your branch's commit log tidy, since we [http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html rebase and squash] before merging into master.
# When you're at a point where you'd like feedback or review (see below for more details), push your branch up to your forked repo: <code>git push origin bug12345</code>
# Create a [https://help.github.com/articles/creating-a-pull-request Pull Request] in github from your bug12345 branch to Mozilla's master branch.
# Copy the URL for your pull request, for example: https://github.com/mozilla/webmaker.org/pull/420
# Go back to Bugzilla, and your bug, and '''Add an attachment'''. You will be given the option to "'''Enter the path to the file on your computer (or paste text as attachment)'''", and since we don't have a file, click '''paste text as attachment'''. Now paste your pull request URL into the textbox.
# For the attachment's '''Description''', once again paste the pull request URL.
# Under '''Flags''' you have a number of options. If your code is ready for review, you can select '''?''' in the drop-down beside '''review''' and then enter the name of the person (i.e., bugzilla email address) that you'd like to look at this code. If it's not ready for review, but you would like feedback, you can do the same thing with '''feedback'''. See the section on code review for more details
# Click '''Submit''' and wait for your reviewer to carry out the review.
As your code is being reviewed, you will likely be asked to make fixes. Here is how you do it
# Go back to your bug fix branch: <code>git checkout bug12345</code>
# Make your changes, commit, and push to your remote repo. The existing pull request will get updated.
# If your reviewer has given you an '''r-''', you may need to ask for review again. You can do this by clicking '''Details''' beside your attachment in Bugzilla, then resetting the '''review''' flag to '''?''' from '''-'''.
Don't be discouraged when this process takes multiple tries. All developers make mistakes, or lack knowledge of the entire project sufficient to catch issues outside the particular code in question. It's common for a bug to take many updates before the code is ready to get checked in (aka., ''landed''). When it's time to land your code, your reviewer will likely ask you to '''rebase'''. It is highly recommended that you ask for help your first time, unless you have experience doing this, as it will alter your branch's commit history. We prefer rebase over merge so that our repositories have clean, single-change master branches, which makes reverting and bisecting much easier. A rebase generally goes like this:
# Switch to your master branch and pull the latest changes from Mozilla: <code>git checkout master && git pull upstream master</code>
# Switch back to your bug branch: <code>git checkout bug12345</code>
# Do a rebase, and ideally an interactive rebase so you can squash and fix your commit message: <code>git rebase master -i</code>. Now your editor will open and you can squash or fixup your separate commits, and redo your original commit message if you don't like it. A common commit message form is: '''Fix Bug 12345: Details about this bug r=person_who_did_review'''.
# Once the rebase is finished, and any conflicts dealt with, push your branch back up to github. You'll need to use the '''-f''' flag in order to force github to take it, since your history has now changed: <code>git push origin bug12345 -f</code>
At this point you can ask your reviewer to land your changes, either via irc, or in a comment in the bug.
TODO:
* code review
* pull requests, inline comments
* flags/whiteboard things to know about (e.g., l10n string changes)
* tagging
* pushing to staging/production
<center>http://farm8.staticflickr.com/7340/9337213776_d77d88eb89.jpg</center>
