Contribute to Greasemonkey

Want to help with Greasemonkey? Great! We need all the help we can get. This page will tell you everything you need to know to get started.

Become a project member

In order to edit tickets, change wiki pages, and otherwise participate in the greasemonkey project, you must become a project member. To do this, email greasemonkey-dev@googlegroups.com and ask to be added to the project_members group on Trac. Everyone is welcome, we mostly do this to combat spam.

Decide what to to

If there is something in particular you want to change in Greasemonkey, then say "Huzzah!" - you're done with this part.

Otherwise, you may want to browse the bug list to find something that needs doing.

Announce your intentions

This step is very important. You should let the Greasemonkey community know what you plan to do before you begin doing it. This prevents duplication of effort and it also gives the community a chance to give you early feedback on your idea before you get very deeply into it.

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 bug entry if applicable.

Get the source code

Greasemonkey source code is managed with Subversion (aka "SVN") at http://svn.devjavu.com/greasemonkey

To use SVN, you need to install an SVN client and "check out" the source code. Here is a quick explanation of how to do this on various platforms. For more information, there is tons of documentation on using SVN available online.

Windows

  1. Install TortoiseSVN
  2. Create a folder to store your Greasemonkey files in. For the sake of conversation, let's call this folder 'greasemonkey'.
  3. Right click on the greasemonkey folder and select 'Checkout' from the SVN menu
  4. Paste this URL into the textbox labeled "URL of Repository": http://svn.devjavu.com/greasemonkey
  5. Press OK. All the greasemonkey files will be downloaded into the folder.

Mac

TODO

Linux 

mkdir greasemonkey
svn checkout http://svn.devjavu.com/greasemonkey greasemonkey

(Optional) Start a branch

If you are implementing a large change, you will find it more convenient to start a branch that you can check into periodically before merging into the main Greasemonkey source. This has several advantages:

  • If your computer melts down, you won't lose your work because it's checked into the Greasemonkey repository
  • IF you get bored with your change, somebody else can pick up later where you left off
  • If you want feedback while you're working, it's easier for the community to see what you changed by comparing a branch to the trunk.

If you want to start a branch for your change, you will need SVN commit access. Mail greasemonkey-dev and we will add you. Once you have access, you should use a command like the following to create your branch: 

svn copy trunk branches/<new branch name>

See the existing branches for examples of branch names.

Set up your development profile

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

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 

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

Mac

TODO

NOTE

The instructions above all specify starting firefox with MOZ_NO_REMOTE=1 in the command. This variable 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. All platforms

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.

Implement your change

Now, the easy part :-)

If you are not familiar with Firefox extension developement you will find these resources helpful starting points:

Send your changes for review

Once you are done implementing your change, you should send it to greasemonkey-dev for review. There are two main ways to do this:

  • If you were working on a branch, send us a link using the Trac tool: http://greasemonkey.devjavu.com/projects/greasemonkey/anydiff
  • If you weren't working on a branch, generate a "patch file" and send it to greasemonkey-dev:
    • Windows: Right-click on the greasemonkey folder and select svn > diff
    • Linux: from the root source directory: svn diff > /tmp/greasemonkey.patch
    • Mac: TODO

Once you send your change, there will hopefully be some feedback from the community. Continue in an iterative fashion, collecting feedback, making changes, etc, until everyone agrees that you are done. If you weren't working on a branch, request SVN commit access. Once you get it, you will be able to check in.

A new Greasemonkey version is released on the first Thursday of every month, as long as there are changes to release.

Style Guide

  • Code should of course work and be correct.
  • Greasemonkey follows the Mozilla JavaScript style guide.
  • Maintainability is crucial: treat your code as primarily for humans to read, and only incidentally for computers to run.
  • Performance is nice, but prior rules should never suffer for it, unless there is a performance problem to address.
  • Feel free to use Javascript 1.6 (Firefox 1.5) features; 1.7 (Firefox 2) or 1.8 (Firefox 3) is off limits, for the time being.
  • Keep acronyms like URL in identifiers all caps, but abbreviations are still capitalized like normal words.