289
edits
Changes
Beginner's Guide to Hacking Sunbird/Lightning
== Beginner's Guide to Hacking Sunbird/Lightning ==
So, you think you might want to help out with the Sunbird or Lightning projects? Great! What's that? You don't have any idea where to begin? Hopefully this document can help. It's designed to be an introduction to submitting your first patch(es) to the Mozilla Sunbird and/or Lightning projects.
=== Getting the right tools ===
Before you can begin, you're going to need several tools setup on your computer.
'''Note:''' Some hackers have found it useful to simply begin by building Sunbird or Lightning from source. ([http://gemal.dk/mozilla/build.html Windows Instructions]) If you can do this, you will (almost) automatically have all the right tools to begin hacking. However, since building is a rather complicated process, you may wish to come back to it at a later stage.
You will need:
* [https://bugzilla.mozilla.org/createaccount.cgi A Bugzilla account]
* A jar extract/build tool.
** Most zip utilities are capable of working with .jar files as well. Some may require that you rename .jar files to .zip first
* A [http://ftp.mozilla.org/pub/mozilla.org/calendar/sunbird/nightly/latest-trunk/ current nightly build] of either Sunbird or Lightning
** Note that this is not the same as the 0.3a1 release build of Sunbird
* A text-editor
** Windows users can use Notepad, if they like pain. Don't use complex document software like Word or OpenOffice.
* A program capable of creating DIFF files (Most CVS programs are capable of doing this.)
* A CVS program (kinda optional, but not really)
'''Linux users''' will find most of these programs available by default with their distro.
'''Windows users'''... (XXX redrenius/ssitter/other windows hackers help me out)
=== Hacking! ===
Time to make your first changes to the code. We're going to use Sunbird as an example.
1.) If you haven't done so already, unzip your current nightly build of Sunbird and make sure it runs properly. Then close it.
2.) Open the 'chrome' folder inside the folder where you unzipped Sunbird.
3.) Find the calendar.jar file and open it with your jar tool.
Inside here you will find 3 folders: <tt>content, locale,</tt> and <tt>skin</tt>.
* <tt>content</tt> holds all of the XUL and JavaScript files that form the Sunbird front-end code. This is where the majority of hacking takes place.
* <tt>locale</tt> holds all of the strings (words/letters) that are used throughout the program. Keeping these separate allows for easy localization of Sunbird.
* <tt>skin</tt> holds all of the icons and CSS files for Sunbird. Keeping this separate allows for Sunbird to be easily themed.
==== XUL Hacking ====
Our first hack is going to be to change the name of tab that holds the minimonth (the small calendar in the upper-left of the screen). If you recall back to the days of Sunbird 0.2, this tab used to say 'Calendar'. However, since the other tab is named 'Calendars', it was confusing, and so it was changed in Bug 270907. We're going to try to change it back, just as an exercise. (DON'T CLICK THAT LINK YET. Try to work through this on your own. If you get stuck, you can look at the patch in that bug for guidance, though.)
4.) The main Sunbird window lives in the calendar.xul file inside <tt>content/calendar</tt>. Open this file in your text-editor.
5.) Scroll down until you see something that looks like:
<tt> <vbox id="left-hand-content" persist="width">
<tabbox id="tablist" persist="selectedIndex">
<tabs>
<tab label="&calendar.calendartab.label;"/>
<tab label="&calendar.listofcalendarstab.label;"/>
</tabs>
</tt>
Here are our tab labels. It's a bit confusing since they don't actually say 'Date' and 'Calendar'. For more information on how localized strings work, see [http://xulplanet.com/tutorials/xultu/locale.html XULPlanet's article]
6.) Change <tt>label="&calendar.calendartab.label;"</tt> to read <tt>label="Calendar"</tt> and save the file.
7.) Place your new calendar.xul back inside <tt>content/calendar</tt> (overwriting the old one) and close the jar tool.
8.) Restart Sunbird and observe the renamed tab.
Yay! Great work. You just made your first changes to the code. There's only one problem... remember how we said earlier that all strings live in <tt>locale</tt>? Well, 'Calendar' here is living in <tt>content</tt> which is bad. Change the line back to <tt>label="&calendar.calendartab.label;"</tt> and restart Sunbird to make sure you did it correctly.
9.) The majority of the strings for Sunbird live in <tt>calendar.dtd</tt> instead the <tt>locale/en-US</tt> folder. Open it in your text editor. '''Note:''' Changes to strings are always made first to the en-US file. Other localizers will then update there files (often only prior to a release) to the new strings. Patches involving string changes/additions/deletions should only change en-US files.
10.) Find the ENTITY named <tt>calendar.calendartab.label</tt> and chance its value from 'Date' to 'Calendar'. Save the file.
11.) Put the new <tt>calendar.dtd</tt> file in your calendar.jar (overwriting the old file) and close the jar tool.
12.) Restart Sunbird and observe the changes.
Congratulations, this is the proper way to change that string.
==== JS Hacking ====
No hacking introduction would be complete without a 'Hello World' example of some sort. So, here's ours. Start with steps 1-3 above.
4.) The main Sunbird front-end loading takes place in <tt>calendar.js</tt> in the function <tt>calendarInit()</tt> Open that file in your text-editor.
5.) Find the <tt>calendarInit()</tt> function. (You'll need to scroll down somewhat.)
6.) Insert the following (after the '{'):
<tt>alert('Hello World!');</tt>
and save the file.
7.) Place your new calendar.js back inside <tt>content/calendar</tt> (overwriting the old one) and close the jar tool.
8.) Restart Sunbird and observe the 'Hello World!' greeting.
=== Finding a bug to fix===
So, by now you're (hopefully) eager to actually fix some real bugs! You may have come here because you already had a bug you wanted to fix. If so, great! The best bugs to fix are usually the ones that annoy you personally. If not, look at the list of [https://bugzilla.mozilla.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Calendar&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=%5Bgood+first+bug%5D&keywords_type=allwords&keywords=&bug_status=NEW&resolution=DUPLICATE&resolution=---&emailassigned_to1=1&emailtype1=exact&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailtype2=exact&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= good first bugs]. (This is currently a short list, but all bug-triagers have now been told to start adding to this list on a more regular basis, so expect it to grow.) Pick one that sounds interesting to you.
If you have the proper Bugzilla permissions, please assign the bug to yourself. If not, please post a comment in the bug saying that you are working on it. '''If you stop working on the bug, please say so as well!'''
Submit a comment with the basic outline of how you plan to fix the bug. (Or if you have IRC access, talk about the proposal there.) There is nothing more frustrating than working hard on a patch, only to be told that the reviewer wanted the patch solved in a different way. Make sure that your proposed changes (ESPECIALLY changes to the User Interface) are acceptable before investing your valuable time.
Now, for the hard-work part: Fix the bug. Continue to make changes to your calendar.jar file and test them by restarting Sunbird. Repeat until the bug is solved.
=== Creating and submitting a patch ===
Wow! You've fixed the bug you were working on? Fantastic! Time to submit a patch so that everyone can enjoy the fruits of your labor. The first thing to recognize is that the files inside calendar.jar are slightly different from the actual source files. In an ideal world, you'll check out the source code and create your patch based on that. If your changes are small however, your reviewer may be willing to accept a chrome patch for the short term. If you plan on submitting several patches, you really need to work from CVS.
1.) Check out the Mozilla source code.
2.) Open up the relevant files and make the same changes to them that you made to your calendar.jar files.
3.) Use your CVS program's diff utility to create a file that contains information about the files you changed. This is usually done with a command something like
<tt>cvs diff -prU 8 mozilla/calendar/ > myPatch.diff</tt>
4.) Go to the bug you've been working on and choose 'Create an Attachment'. Put the path to the file that CVS diff created in the proper box, and give your patch a short title describing your changes. Describe in detail the changes that you've made in the Description box. Check the 'Patch' checkbox under content type.
5.) '''Important:''' Ask for a review! In the dropdown menu next to 'first-review', choose the '?', since you're asking for the review. In the textbox next to the '?' place the email address of one of the calendar peers. It is recommended that you choose 1 of the following people:
*Joey Minta - <tt>jminta@gmail.com</tt>
*Michiel van Leeuwen - <tt>mvl@exedo.nl</tt>
*Dan Mosedale - <tt>dmose@mozilla.org</tt>
Small changes to the code do not need a second-review. If you are unsure about whether you need a second review, say so in your attachment's description. Your first-reviewer will know.
6.) Wait for the review. If you haven't heard anything in 5 days, please 'poke' the review. (Ideally, talk to them on IRC. At a minimum, post a comment in the bug.) If you haven't heard anything in 10 days, please choose a different reviewer.
7a.) If your review request is '''granted:''' Your reviewer will 'check in' your patch and (in most cases) mark the bug as FIXED. You can use [http://bonsai.mozilla.org/cvsquery.cgi?treeid=default&module=CalendarClient&branch=&branchtype=match&dir=%2Fmozilla%2Fcalendar&file=&filetype=match&who=&whotype=match&sortby=Date&hours=2&date=week&mindate=&maxdate=&cvsroot=%2Fcvsroot Bonsai] to confirm this. Congratulations! You've just fixed your first bug.
7b.) If your review request is '''denied:''' Don't lose heart! This happens more often than not. Your reviewer will tell you changes that need to be made to the patch in order for it to be acceptable for checkin. Repeat this process with those changes in mind, submit another patch, and ask for another review.
==== Tips for making good patches ====
* Comments inside the code are encouraged! Remember, someone else is going to have to go back and read your code later without any clue of what you were thinking when you were doing it. Make sure that this can be done with as little pain as possible
* Don't just fix things, fix them correctly. If you find yourself adding lots of special cases for what seems like a simple task, the patch probably won't be approved without a very good reason. Mozilla code is complicated enough as it is, don't make it more so.
* Be careful about random whitespace changes. Don't add newlines to irrelevant areas, and make sure you remove extra newlines you added while experimenting.
* While alert() (and it's cousin dump()) are useful for debugging, they should not remain in code that will be checked in. Remove any alert()s you may have used for testing.
* Use spaces, NOT tabs.
* Follow the existing style of the document you're working on. If default indenting is 4 spaces, use 4 spaces. If it's 2, use 2. If braces are placed on the same line as <tt>for</tt> and <tt>if</tt> (ie <tt>if (a == b) {</tt>) keep it this way. If they're on the next line, keep it that way.
* Don't be afraid to ask for help!
=== Useful hacking tools ===
* [irc://irc.mozilla.org IRC] - Sunbird and Lightning hackers and reviewers like to hang out in the #calendar channel on irc.mozilla.org. They're usually more than happy to answer your questions if you get stuck on a part of a patch. '''Be patient''' when asking questions, though. Hackers have to sleep, eat, and work too, so it may take several hours before someone sees your question and responds.
* [http://lxr.mozilla.org/mozilla/ LXR] - Great for searching the mozilla codebase for examples, particular code lines, etc.
* [http://www.xulplanet.com/ XULPlanet] - a great reference on all things XUL.
* [http://developer.mozilla.org/ DevMo] - The Mozilla Developer's Center. Tons of great links and articles on almost everything Mozilla-hackish imaginable.
* Sunbird developer's guide. - Not written yet, but hopefully coming soon.
=== Other possibly useful links ===
*[http://developer.mozilla.org/en/docs/Sunbird_Theme_Tutorial Sunbird theme creation tutorial]
*[http://developer.mozilla.org/en/docs/Hacking_Firefox Hacking Firefox Guide]
So, you think you might want to help out with the Sunbird or Lightning projects? Great! What's that? You don't have any idea where to begin? Hopefully this document can help. It's designed to be an introduction to submitting your first patch(es) to the Mozilla Sunbird and/or Lightning projects.
=== Getting the right tools ===
Before you can begin, you're going to need several tools setup on your computer.
'''Note:''' Some hackers have found it useful to simply begin by building Sunbird or Lightning from source. ([http://gemal.dk/mozilla/build.html Windows Instructions]) If you can do this, you will (almost) automatically have all the right tools to begin hacking. However, since building is a rather complicated process, you may wish to come back to it at a later stage.
You will need:
* [https://bugzilla.mozilla.org/createaccount.cgi A Bugzilla account]
* A jar extract/build tool.
** Most zip utilities are capable of working with .jar files as well. Some may require that you rename .jar files to .zip first
* A [http://ftp.mozilla.org/pub/mozilla.org/calendar/sunbird/nightly/latest-trunk/ current nightly build] of either Sunbird or Lightning
** Note that this is not the same as the 0.3a1 release build of Sunbird
* A text-editor
** Windows users can use Notepad, if they like pain. Don't use complex document software like Word or OpenOffice.
* A program capable of creating DIFF files (Most CVS programs are capable of doing this.)
* A CVS program (kinda optional, but not really)
'''Linux users''' will find most of these programs available by default with their distro.
'''Windows users'''... (XXX redrenius/ssitter/other windows hackers help me out)
=== Hacking! ===
Time to make your first changes to the code. We're going to use Sunbird as an example.
1.) If you haven't done so already, unzip your current nightly build of Sunbird and make sure it runs properly. Then close it.
2.) Open the 'chrome' folder inside the folder where you unzipped Sunbird.
3.) Find the calendar.jar file and open it with your jar tool.
Inside here you will find 3 folders: <tt>content, locale,</tt> and <tt>skin</tt>.
* <tt>content</tt> holds all of the XUL and JavaScript files that form the Sunbird front-end code. This is where the majority of hacking takes place.
* <tt>locale</tt> holds all of the strings (words/letters) that are used throughout the program. Keeping these separate allows for easy localization of Sunbird.
* <tt>skin</tt> holds all of the icons and CSS files for Sunbird. Keeping this separate allows for Sunbird to be easily themed.
==== XUL Hacking ====
Our first hack is going to be to change the name of tab that holds the minimonth (the small calendar in the upper-left of the screen). If you recall back to the days of Sunbird 0.2, this tab used to say 'Calendar'. However, since the other tab is named 'Calendars', it was confusing, and so it was changed in Bug 270907. We're going to try to change it back, just as an exercise. (DON'T CLICK THAT LINK YET. Try to work through this on your own. If you get stuck, you can look at the patch in that bug for guidance, though.)
4.) The main Sunbird window lives in the calendar.xul file inside <tt>content/calendar</tt>. Open this file in your text-editor.
5.) Scroll down until you see something that looks like:
<tt> <vbox id="left-hand-content" persist="width">
<tabbox id="tablist" persist="selectedIndex">
<tabs>
<tab label="&calendar.calendartab.label;"/>
<tab label="&calendar.listofcalendarstab.label;"/>
</tabs>
</tt>
Here are our tab labels. It's a bit confusing since they don't actually say 'Date' and 'Calendar'. For more information on how localized strings work, see [http://xulplanet.com/tutorials/xultu/locale.html XULPlanet's article]
6.) Change <tt>label="&calendar.calendartab.label;"</tt> to read <tt>label="Calendar"</tt> and save the file.
7.) Place your new calendar.xul back inside <tt>content/calendar</tt> (overwriting the old one) and close the jar tool.
8.) Restart Sunbird and observe the renamed tab.
Yay! Great work. You just made your first changes to the code. There's only one problem... remember how we said earlier that all strings live in <tt>locale</tt>? Well, 'Calendar' here is living in <tt>content</tt> which is bad. Change the line back to <tt>label="&calendar.calendartab.label;"</tt> and restart Sunbird to make sure you did it correctly.
9.) The majority of the strings for Sunbird live in <tt>calendar.dtd</tt> instead the <tt>locale/en-US</tt> folder. Open it in your text editor. '''Note:''' Changes to strings are always made first to the en-US file. Other localizers will then update there files (often only prior to a release) to the new strings. Patches involving string changes/additions/deletions should only change en-US files.
10.) Find the ENTITY named <tt>calendar.calendartab.label</tt> and chance its value from 'Date' to 'Calendar'. Save the file.
11.) Put the new <tt>calendar.dtd</tt> file in your calendar.jar (overwriting the old file) and close the jar tool.
12.) Restart Sunbird and observe the changes.
Congratulations, this is the proper way to change that string.
==== JS Hacking ====
No hacking introduction would be complete without a 'Hello World' example of some sort. So, here's ours. Start with steps 1-3 above.
4.) The main Sunbird front-end loading takes place in <tt>calendar.js</tt> in the function <tt>calendarInit()</tt> Open that file in your text-editor.
5.) Find the <tt>calendarInit()</tt> function. (You'll need to scroll down somewhat.)
6.) Insert the following (after the '{'):
<tt>alert('Hello World!');</tt>
and save the file.
7.) Place your new calendar.js back inside <tt>content/calendar</tt> (overwriting the old one) and close the jar tool.
8.) Restart Sunbird and observe the 'Hello World!' greeting.
=== Finding a bug to fix===
So, by now you're (hopefully) eager to actually fix some real bugs! You may have come here because you already had a bug you wanted to fix. If so, great! The best bugs to fix are usually the ones that annoy you personally. If not, look at the list of [https://bugzilla.mozilla.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Calendar&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=%5Bgood+first+bug%5D&keywords_type=allwords&keywords=&bug_status=NEW&resolution=DUPLICATE&resolution=---&emailassigned_to1=1&emailtype1=exact&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailtype2=exact&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= good first bugs]. (This is currently a short list, but all bug-triagers have now been told to start adding to this list on a more regular basis, so expect it to grow.) Pick one that sounds interesting to you.
If you have the proper Bugzilla permissions, please assign the bug to yourself. If not, please post a comment in the bug saying that you are working on it. '''If you stop working on the bug, please say so as well!'''
Submit a comment with the basic outline of how you plan to fix the bug. (Or if you have IRC access, talk about the proposal there.) There is nothing more frustrating than working hard on a patch, only to be told that the reviewer wanted the patch solved in a different way. Make sure that your proposed changes (ESPECIALLY changes to the User Interface) are acceptable before investing your valuable time.
Now, for the hard-work part: Fix the bug. Continue to make changes to your calendar.jar file and test them by restarting Sunbird. Repeat until the bug is solved.
=== Creating and submitting a patch ===
Wow! You've fixed the bug you were working on? Fantastic! Time to submit a patch so that everyone can enjoy the fruits of your labor. The first thing to recognize is that the files inside calendar.jar are slightly different from the actual source files. In an ideal world, you'll check out the source code and create your patch based on that. If your changes are small however, your reviewer may be willing to accept a chrome patch for the short term. If you plan on submitting several patches, you really need to work from CVS.
1.) Check out the Mozilla source code.
2.) Open up the relevant files and make the same changes to them that you made to your calendar.jar files.
3.) Use your CVS program's diff utility to create a file that contains information about the files you changed. This is usually done with a command something like
<tt>cvs diff -prU 8 mozilla/calendar/ > myPatch.diff</tt>
4.) Go to the bug you've been working on and choose 'Create an Attachment'. Put the path to the file that CVS diff created in the proper box, and give your patch a short title describing your changes. Describe in detail the changes that you've made in the Description box. Check the 'Patch' checkbox under content type.
5.) '''Important:''' Ask for a review! In the dropdown menu next to 'first-review', choose the '?', since you're asking for the review. In the textbox next to the '?' place the email address of one of the calendar peers. It is recommended that you choose 1 of the following people:
*Joey Minta - <tt>jminta@gmail.com</tt>
*Michiel van Leeuwen - <tt>mvl@exedo.nl</tt>
*Dan Mosedale - <tt>dmose@mozilla.org</tt>
Small changes to the code do not need a second-review. If you are unsure about whether you need a second review, say so in your attachment's description. Your first-reviewer will know.
6.) Wait for the review. If you haven't heard anything in 5 days, please 'poke' the review. (Ideally, talk to them on IRC. At a minimum, post a comment in the bug.) If you haven't heard anything in 10 days, please choose a different reviewer.
7a.) If your review request is '''granted:''' Your reviewer will 'check in' your patch and (in most cases) mark the bug as FIXED. You can use [http://bonsai.mozilla.org/cvsquery.cgi?treeid=default&module=CalendarClient&branch=&branchtype=match&dir=%2Fmozilla%2Fcalendar&file=&filetype=match&who=&whotype=match&sortby=Date&hours=2&date=week&mindate=&maxdate=&cvsroot=%2Fcvsroot Bonsai] to confirm this. Congratulations! You've just fixed your first bug.
7b.) If your review request is '''denied:''' Don't lose heart! This happens more often than not. Your reviewer will tell you changes that need to be made to the patch in order for it to be acceptable for checkin. Repeat this process with those changes in mind, submit another patch, and ask for another review.
==== Tips for making good patches ====
* Comments inside the code are encouraged! Remember, someone else is going to have to go back and read your code later without any clue of what you were thinking when you were doing it. Make sure that this can be done with as little pain as possible
* Don't just fix things, fix them correctly. If you find yourself adding lots of special cases for what seems like a simple task, the patch probably won't be approved without a very good reason. Mozilla code is complicated enough as it is, don't make it more so.
* Be careful about random whitespace changes. Don't add newlines to irrelevant areas, and make sure you remove extra newlines you added while experimenting.
* While alert() (and it's cousin dump()) are useful for debugging, they should not remain in code that will be checked in. Remove any alert()s you may have used for testing.
* Use spaces, NOT tabs.
* Follow the existing style of the document you're working on. If default indenting is 4 spaces, use 4 spaces. If it's 2, use 2. If braces are placed on the same line as <tt>for</tt> and <tt>if</tt> (ie <tt>if (a == b) {</tt>) keep it this way. If they're on the next line, keep it that way.
* Don't be afraid to ask for help!
=== Useful hacking tools ===
* [irc://irc.mozilla.org IRC] - Sunbird and Lightning hackers and reviewers like to hang out in the #calendar channel on irc.mozilla.org. They're usually more than happy to answer your questions if you get stuck on a part of a patch. '''Be patient''' when asking questions, though. Hackers have to sleep, eat, and work too, so it may take several hours before someone sees your question and responds.
* [http://lxr.mozilla.org/mozilla/ LXR] - Great for searching the mozilla codebase for examples, particular code lines, etc.
* [http://www.xulplanet.com/ XULPlanet] - a great reference on all things XUL.
* [http://developer.mozilla.org/ DevMo] - The Mozilla Developer's Center. Tons of great links and articles on almost everything Mozilla-hackish imaginable.
* Sunbird developer's guide. - Not written yet, but hopefully coming soon.
=== Other possibly useful links ===
*[http://developer.mozilla.org/en/docs/Sunbird_Theme_Tutorial Sunbird theme creation tutorial]
*[http://developer.mozilla.org/en/docs/Hacking_Firefox Hacking Firefox Guide]
