Contributing to Greasemonkey

Want to help with Greasemonkey? Great! We need all the help we can get.

Here's how to get started:

Decide what to to

All changes to Greasemonkey should be associated with a bug in the Greasemonkey Bugs Database.

If there is a feature that you want that doesn't exist yet, that is a bug too, so go ahead and create an account and add it. But first, make sure it isn't already there.

If you don't have anything in particular you want to do, then just pick something from the bugs database. Bugs are categorized by priority (P1 is the highest, P5 is the lowest).

Announce your intentions

This step is very important. You should communicate what you intend to do with the Greasemonkey community before you begin doing it. If you don't do this, we may request significant changes before accepting it, or we may not accept it at all.

To announce your intentions, join greasemonkey-dev@googlegroups.com at http://groups.google.com/group/greasemonkey-dev and send us a note saying what you want to change. Include the link to the BugsDB entry.

There will likely be discussion in the comments of the bug as to the appropriate strategy for the design and implementation. Once there is consensus, you can assign the bug to yourself and begin your implementation.

Get the source code

Greasemonkey source code is manage with CVS. Using CVS means that we can see all the changes that anyone has ever made to Greasemonkey, and can always roll back to some earlier state if something gets broken.

To use CVS, you need to install a CVS client and "check out" the source code. Note that the guest login (used in examples below) has a password of guest.

Here is a quick explanation of how to do this on various platforms:

Windows

• Install TortoiseCVS
• Create a folder to store your Greasemonkey files in. For the sake of conversation, let's call this folder 'greasemonkey'.
• Right click on the greasemonkey folder and select 'new module' from the CVS menu
• Paste this string into the CVSROOT textbox: :pserver:guest@mozdev.org:/cvs
• Press OK. All the greasemonkey files will be downloaded into the folder.

Mac

• TODO

Linux

• mkdir greasemonkey
• cvs -d :pserver:guest@mozdev.org:/cvs login
• cvs -z3 -d :pserver:guest@mozdev.org:/cvs co greasemonkey

Implement your change

Greasemonkey is easy to hack on because it has a quick edit/test cycle. Here is how to set it up.

Set up your development profile

You will want to have a separate Firefox profile for developing Greasemonkey. It's useful because you can have your regular Firefox profile open for reading email and checking documentation without having to constantly restart it when you want to test your changes to GM.

Also, if something you change happens to corrupt your profile, you won't destroy your main one :-)

To set up a new Firefox profile, you can use the regular Firefox Profile Manager, but I think it is easier to create the directory yourself:

Windows

1. Create a new folder anywhere you want, let's say "c:\gmprofile".
2. Inside the folder, create a new folder, called "extensions".
3. Inside that folder, create a new text file called {e4a8a97b-f2ed-450b-b12d-ee082ba24781} (including the curly braces). It's important the file not have ".txt" at the end.
4. Open the text file and enter the path to the src folder inside your Greasemonkey checkout. So if you checked out to c:\greasemonkey then you would enter c:\greasemonkey\src inside the text file.
5. Close any open Firefox windows
6. Open a command prompt by going to Start > Run > and typing "cmd".
7. Run firefox with this command: MOZ_NO_REMOTE=1 c:\program files\firefox\firefox.exe -profile c:\gmprofile.

Obviously, you will need to change the path to firefox.exe to be correct for your system. You can find the path to firefox.exe by right-clicking on any firefox icon and showing it's properties.

Linux

1. mkdir -p gmprofile/extensions
2. echo 'path/to/greasemonkey/checkout/src' > gmprofile/extensions/{e4a8a97b-f2ed-450b-b12d-ee082ba24781}
3. MOZ_NO_REMOTE=1 firefox -profile gmprofile

Mac

TODO

The MOZ_NO_REMOTE=1 part of the command allows other firefox profiles to be run at the same time. So now, you should be able to open your regular firefox at the same time and use it to browse docs or check mail or whatever.

Your development cycle will now be something like this:

1. Edit files in your greasemonkey source checkout
2. Restart firefox (using MOZ_NO_REMOTE=1... command)
3. Test change
4. Rinse, repeat

No separate compile step is necessary.

Send your changes for review

Changes to any open source project are communicated by way of something called a "patch" or "diff" file. This is a special file that shows the changes you have made on your private copy of Greasemonkey. You can generate one using your CVS client.

• Windows: Right-click on the greasemonkey folder and select cvs > diff
• Linux: from the root source directory: cvs diff > /tmp/greasemonkey.patch
• Mac: TODO

Take your patch file and attach it to the bug with a description of what you have done. There will hopefully be some feedback from the community. Continue in an iterative fashion, collecting feedback, making changes, etc, until you believe you are done and everyone else does too.

Once this occurs, the Greasemonkey admins (currently just Aaron) will decide which release your change should appear in. Usually this will just be the next one. Someone with access to commit changes to source control (currently Jeremy, Aaron, and Nickolas) will submit your changes and add you to the contributors list in the install.rdf file.

Style Guide

Greasemonkey does not have an official style guide for patches, but patchers should adhere to mozilla's style guide where appropriate, and note the following extra standardizations:

• Surround operators with a space on either side eg. a = 1 NOT a=1
• Use double quotes in preference to single quotes