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. Make sure it isn't already there yet first.

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, there's no guarantee that we won't request significant changes before accepting it, or that we will 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. 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 login*
• 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 in development mode because it has a quick edit/run test cycle. Here is how to set it up:

• Setup a separate profile for GM hacking. You will want this so that you can refer to documentation and email in your normal profile without constantly shutting down your browser to test GM changes.
  • Create a new folder called anything you want. Let's call it "gmprofile" for now.
  • Inside "gmprofile" create an "extensions" folder, and inside that, create a text file called "{e4a8a97b-f2ed-450b-b12d-ee082ba24781}". Make sure there is no ".txt" extension. This is the GUID of the Greasemonkey extension.
  • Open the text file and inside it put the full path to the src folder inside your greasemonkey checkout. So let's say that you checked out greasemonkey to "c:\greasemonkey" on windows. Inside the text file you would enter "c:\greasemonkey\src".
• Start Firefox using the new profile.
  • Windows: Start, run, command. In the command prompt, enter: *MOZ_NO_REMOTE=1 c:\program files\mozilla\firefox\firefox.exe -profile c:\gmprofile*. You might need to modify the path to Firefox if it's different on your system. You can find the correct path by right clicking on any firefox icon on your desktop or start menu and going to properties.
  • Linux: *MOZ_NO_REMOTE=1 firefox -profile /home/youruser/gmprofile*
• You should now be running Firefox in a separate profile just for GM. You can verify this by seeing that the Greasemonkey icon is in the status bar, and that none of the history and settings from your regular profile are present.
• Now, edit the Greasemonkey sources in your checkout. Whenever you want to test them, run the command to start the gmprofile firefox. You can keep your regular browser open at the same time.

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 checkout folder, enter *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, a release will be decided upon that your change should appear in! One of the Greasemonkey admins (currently Jeremy and Aaron) will submit your change to the actual trunk.