From MozillaWiki
< Webmaker‎ | Code
Jump to: navigation, search

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 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 Pro Git, online book.

A typical workflow looks like this:

  1. Fork the appropriate repo into your own github account
  2. Clone your fork locally: git clone --recursive {url to your github repo}. NOTE: many Webmaker repos have submodules, so it's wise to clone recursively.
  3. Add Mozilla's repo as an upstream remote, so you can stay in sync: git remote add upstream {url to Mozilla's github repo}. NOTE: you can call it anything you like, but upstream is a common convention.
  4. Create a new branch off master, using the bug number as the name: git checkout -b bug12345
  5. Work on the code, committing as you go. Don't worry about keeping your branch's commit log tidy, since we rebase and squash before merging into master.
  6. 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: git push origin bug12345
  7. Create a Pull Request in github from your bug12345 branch to Mozilla's master branch.
  8. Copy the URL for your pull request, for example: https://github.com/mozilla/webmaker.org/pull/420
  9. 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.
  10. For the attachment's Description, once again paste the pull request URL.
  11. 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
  12. Click Submit and wait for your reviewer to carry out the review.

3. Get your code Reviewed

Code review is a critical component of the Mozilla project. Code review increases code quality, distributes knowledge of changes across a team, allows for mentorship of new developers, etc. All changes in Webmaker need review, from a single line change to a 5,000 line feature addition. There are no exceptions, and no one is "good enough" to skip having their code reviewed.

In order to get your code reviewed, you first need to find an appropriate reviewer. There are a few strategies. The first is to ask in the bug, on irc, or the dev list. The second is to look at git blame {filename} information, which will show you who touched the code you're working in last, and often who did the review (e.g., the commit message or bug that changed it will have that info).

Your reviewer will use a mixture of inline Github code comments and comments in the Bugzilla bug. Generally speaking, issues relating to the code itself will go in Github, and general comments in Bugzilla. As your code is being reviewed, you will likely be asked to make fixes. This will include fixing errors, adding comments, adhering to prevailing styles, etc. Here is how you do it:

  1. Go back to your bug fix branch: git checkout bug12345
  2. Make your changes, commit, and push to your remote repo. The existing pull request will get updated.
  3. 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 update your branch to the latest code in Mozilla's master branch yet--we'll do that when it's ready to land and we rebase (see below).

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:

  1. Switch to your master branch and pull the latest changes from Mozilla: git checkout master && git pull upstream master
  2. Switch back to your bug branch: git checkout bug12345
  3. Do a rebase, and ideally an interactive rebase so you can squash and fix your commit message: git rebase master -i. 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.
  4. 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: git push origin bug12345 -f

At this point you can ask your reviewer to land your changes, either via irc, or in a comment in the bug.

TODO: document whiteboard flags

  • l10n changes
  • sumo or other doc changes
  • other?

4. Verify your code on Staging


  • tagging
  • pushing to staging/production