Thursday, August 21, 2008

Tips & Tricks for a new sponsoree

I've recently been moved behind the firewall and am intern-ing at Sun.

One of the tasks of this job that I've been charged with is to sponsor community code contributions going in to OpenSolaris and I noticed a bunch of things that'd just make it less work & by extension time to go from an email with a .diff in it to integration. Let's begin:

So you want to go that extra mile for your sponsor:

You've signed your SCA , found a bug, sent your email to the list, and are ready to roll.
Awesome! OpenSolaris is huge and we appreciate the extra hands, plus you help make it more community driven.

So the next step is to go back and forth with your sponsor trying to find the best possible solution to the bug. Once you've done that, you can get down to work, fix the bug, and then build & test it.

Then you just send the code to your sponsor, and you're done right?
Well, you could do that. It's technically correct and is the standard way of doing things but if you really want to wow your sponsor and go above and beyond, there are a couple things that the gatekeepers require that you can do to make his or her job ( taking your code, committing it to the tree ) a breeze:
  • unified diffs : from the top of the tree, running a diff -u gives you a single patch file that can be applied to the tree, rather than a diff of every affected file. Better still is an hg export file. The standard comment for HG exports is :
    Contributed by {your name} <{your email}>
    {bug id} {bug synopsis}
    note the single space between bug id and bug synopsis
  • recent gate checkout : a bunch of stuff may have changed in the meantime, so it's best to apply your code to a copy of the ON gate as recent as possible, so that the diff doesn't break
  • cstyle clean it : onbld has a tool in /opt/onbld/bin called 'cstyle' which checks to make sure that the pendantic little nits like indentation standards are adhered to. You only need to make the stuff you changed cstyle clean, don't worry about all the old stuff
  • change the copyright : you'll notice every file owned by Sun in the ON consolidation that has a line with Sun's copyright in it like:
    * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
    * Use is subject to license terms.
    These all need to be updated to reflect the current year ( in this case it's 2008 ) whenever the file changes.
  • Update the CDDL block: Some older files have a CDDL block that's no longer acceptable, so if you run across it you may need to update it. You'll be able to tell, because it gives a version number ( 1.0 ) of the license. So, update this:
    The contents of this file are subject to the terms of the
    Common Development and Distribution License, Version 1.0 only
    (the "License"). You may not use this file except in compliance
    with the License.
    To this:
    The contents of this file are subject to the terms of the
    Common Development and Distribution License (the "License").
    You may not use this file except in compliance with the License.

  • SCCS keywords : the ON gate used to use a different source-code management system (teamware). The gate is now managed by Mercurial. As a result, there's still some vestigial teamware bits lying around. Before a change can be integrated someone ( typically the sponsor, but it could be you, which is why we're here ) needs to remove the old SCCS keywords. They look like this:
    #pragma ident "%Z%%M% %I% %E% SMI"
    This whole line can just be removed from the file entirely. It's not needed anymore.
With these simple steps, you can cut (depending on the size of the patch) hours off your sponsor's task and surprise them with how thorough you are