Code‎ > ‎

Submitting code

The process for submitting a patch to the wave-protocol repository is:

  1. Clone or pull/update the wave-protocol mercurial repository
  2. Make changes
  3. Use the request_codereview script to set up a code review at http://codereview.waveprotocol.org
  4. Wait for reviewers' comments, address them, repeat until everybody is happy
  5. A maintainer will submit your patch (credited to you, of course)
  6. Before any contributions are accepted you will need to sign the Google Wave Contributors License Agreement. The are two forms, one for Individual Contributors, and a separate one for Corporate Contributors (see current Individual ContributorsCompany Contributors).

Note that the code, draft specifications, and whitepapers are all in the same repository and changes to any of them should follow this process.

Style

Take care to conform to the style of the file you're patching (there are Eclipse formatter and import order configurations in some repositories). If in doubt follow Sun's Java style guide. The following should also be observed when submitting code:

  • Keep lines to under 100 characters, comment lines under 80 characters
  • Indentation is 2 spaces (no tabs, ever)
  • Alphabetic ordering of imports (though IDEs do this automatically)

In addition, reading Effective Java it is strongly suggested.

Make changes

If you add files then remember to hg add them. You can check the status of important files using hg stat -arm and hg diff.

Use request_codereview script

We use the Rietveld code review tool to submit a code review. This looks at the difference between the tip of the repository (or a specific version with --rev) and its current state, and uploads it to http://codereview.waveprotocol.org for other people to comment on. We use this both as a mechanism for distributing patches, and as a way to ensure they are a suitably high quality.

Use hg log to find the revision number(s) before your changesets.

$ ./request_codereview --send_mail -r reviewer@gmail.com,... [--rev=rev_before_change]

Options:

  • --send_mail posts your patch to the wave-protocol-code-discuss@googlegroups.com (otherwise no-one will know)
  • -e example@gmail.com is your Google account email address
  • -m "Short description of patch" is a short summary of what the patch does (limited to 100 characters) -- if you need a longer description, use -d "long description" or -f description-file-name in addition to -m
  • -r reviewer@gmail.com,... comma separated list of reviewers.

You should specify one or more reviewers who are project committers. If you don't specify any reviewers people may assume your patch is not yet ready for review. Try to choose a reviewer who has worked on related regions of code before, but if you can't tell then pick anyone and they will reassign if necessary.

You will be prompted for a password for the account specified with the -e flag - this will be your login password, not your Google Code password.

You can view your patch at http://codereview.waveprotocol.org. Log in for a more detailed overview.

Wait for reviews

Reviewers (probably the wave-protocol maintainers, though anybody is welcome) will comment on your patch, either inline or with an overall comment. Look out for the phrase LGTM ("Looks Good To Me").

You should revise the code if requested, and reply to the comments either with "Done." or a more detailed response if necessary.

Updating your patch

When you make some changes to your patch, e.g. in response to reviewers' comments, you should update your patch so that your changes can be reviewed. Use the request_codereview script with a -i parameter specifying the issue number of the patch. For example, if the issue number is 22222, the command may be:

$ ./request_codereview -i 22222 [--send_mail]

This will create a new patch-set inside the patch review issue. The -m message parameter is optional.

More complicated patches - making a clone

After code review against trunk, if the patch touches more than 1 or 2 files, it will make everyone's life easier if you push the changes to a clone on code.google.com

In the web interface on code.google.com, click 'Source' tab, then the 'Clones' link.

Create a new clone for yourself.

From your local HG repo, push to the newly created clone with

$ hg push https://clonename.googlecode.com/hg/

Submitting your patch

After an LGTM or two, a maintainer will download your patch from Rietveld and submit it to the mainline repository.

Example

For an example, we change the client's scrolling keys to be [ and ] instead of { and }.

$ hg clone https://wave-protocol.googlecode.com/hg/ wave-protocol$ cd wave-protocol
$ vim src/org/waveprotocol/wave/examples/fedone/waveclient/console/ConsoleClient.java
...
$ hg stat -arm
M src/org/waveprotocol/wave/examples/fedone/waveclient/console/ConsoleClient.java
$ hg diff
diff -r 9fb7aab3e2a9 src/org/waveprotocol/wave/examples/fedone/waveclient/console/ConsoleClient.java
--- a/src/org/waveprotocol/wave/examples/fedone/waveclient/console/ConsoleClient.java Thu Aug 20 14:18:49 2009 +1000
+++ b/src/org/waveprotocol/wave/examples/fedone/waveclient/console/ConsoleClient.java Sun Aug 23 12:29:51 2009 +1000
@@ -114,7 +114,7 @@
 
     // Set up scrolling -- these are the opposite to how you would expect because of the way that
     // the waves are scrolled (where the bottom is treated as the top)
-    reader.addTriggeredAction('}', new ActionListener() {
+    reader.addTriggeredAction(']', new ActionListener() {
       @Override public void actionPerformed(ActionEvent e) {
         if (isWaveOpen()) {
           openWave.scrollUp(scrollLines.get());
@@ -123,7 +123,7 @@
       }
     });
 
-    reader.addTriggeredAction('{', new ActionListener() {
+    reader.addTriggeredAction('[', new ActionListener() {
       @Override public void actionPerformed(ActionEvent e) {
         if (isWaveOpen()) {
           openWave.scrollDown(scrollLines.get());
$ ./request_codereview --send_mail -e example@gmail.com -m "Console client: use [ and ] rather than { and } to scroll"
Upload server: codereview.waveprotocol.org (change with -s/--server)
Loaded authentication cookies from /Users/example/.codereview_upload_cookies
Issue created. URL: http://codereview.waveprotocol.org/8002
Uploading base file for src/org/waveprotocol/wave/examples/fedone/waveclient/console/ConsoleClient.java


Comments