How to submit code to be included with Watir

Should your code be part of Watir?

There are many ways to share code you've written with other Watir users. If you have examples of code using Watir or extenstions to Watir that you think others can learn from, you can post your code directly to this wiki. Any Watir user is allowed to do this, and by doing this, you are giving back to the community and helping out. The Examples wiki page lists Watir code written by users.

However, some code really should be included with Watir. If you have fixed a bug in Watir, improved compatibility, or added a feature that belongs in the core Watir classes, it should be included in Watir. Sometimes, it is hard to say. If you are unsure, you can always post your code to one of the above pages and then also suggest that it be incorporated in Watir.

New features to Watir will be considered when they meet the following criteria.

• They are intuitive and consistent with the rest of Watir. People love Watir because they can just read Watir code and just understand what it does. New features must be equally intuitive.
• Unit tests must be provided. Unit tests allow us to refactor the Watir code base with out fear of breaking it. They also help us ensure compatibility across browsers.
• The functionality must clearly belong to Watir. Watir is a browser driver. Not all code that is useful to Watir testers necessarily belongs to Watir.

Sometimes people ask us whether we would welcome a particular feature. These questions are usually much easier for us to answer when they accompany sample code, of use or implementation.

Developing your code

If you are planning to develop code contributions to Watir itself, you should be doing your development out of Subversion. You should not be directly editing the source in your gem directory. By developing out of Subversion, you will be able to submit your changes in a form that we can directly apply and commit.

These instructions assume that you are familiar with Subversion (SVN). If you are new to SVN, you need to create your own sample repository and experiment with that. This will give you the knowledge and confidence you'll need to work SVN on a public open-source project.

After you have developed your code and ran the unit tests (passing of course), you can use SVN to create a patch file. This is what we expect from contributors. A patch file is an annotated diff that shows what code you changed and what code (revision) you started with. Patches are easy to review by humans, and equally easy to apply to a working directory using SVN. We don't explain SVN because (1) there are many different clients you can use and (2) it is constantly being updated. However we can say that Tortoise SVN is reliable and easy to learn. This page also provides some detailed instructions on how to use an old version of Eclipse for Watir Development: How To Update RDOC and Submit Patches

We often get submissions of code in the form of, well, code. People edit the source (from the gem directory presumably) and then send us the edited files. These are hard for us to process, and often just lay around ignored. First of all, we can't just look at the code to see if the changes are worthwhile. The first thing we have to do is figure out where you started from (or guess) and then create a working directory based on that and then drop in your files. After we've done this, we can see your changes, run the unit tests and decide whether to go forward. But it really helps us if you can do this first. Because the next step, whether it is you or one of us, is to create the patch file. SVN does this easily.

Testing your code

You should run the unit tests on your code before you submit it to us. It is the first thing we are going to do with your code. About half the time code submissions fail right here, believe it or not. Running Unit Tests in Development

In fact, it would be a good idea to run the unit tests before you make any changes to the code. If you see any failures you know it is your configuration, or a problem with the tests, and not something that you broke.

If you have found a bug, it would be great if you also wrote a unit test that demonstrates the bug, and thus demonstrates that you've fixed the bug. This way we won't have to worry about a future refactoring reintroducing the problem.

Even if you only give us a failing test – and not a fix – that is valuable. Indeed, if we have the choice of getting only a test or only a fix, we'd often prefer getting the test. In their hearts, testers know that testing is harder than coding, but when it comes to Watir many of them fall into the trap of thinking that the code is more important. Not true! We love tests.

If you are adding a new feature to Watir, unit tests are critical. Because Ruby is an open language, any one can distribute code that adds features to Watir. It doesn't have to be part of the Watir distribution. When we add a feature to Watir we make an ongoing commitment to support the feature going forward. We need tests to do this.

Updating your working copy

After you have written your code and tested it, you'll probably have to update you code. As you've been working on your code, so have other Watir contributors. And if much time has passed, it is likely that some of their contributions have been committed to trunk. If you create a patch before updating, then another Watir contributor will have to merge your changes into the latest trunk. It's better if you do this yourself. Indeed, if you make a habit of doing this everday, it won't be a big chore at the end.

Submitting your patch

Subversion has a command to create a patch. In the command line, it is "svn diff", in Tortoise or Subclipse it is "create patch". This creates a file that you should attach to a Jira ticket. Feel free to also send us email if you'd like to discuss it with us.

Wouldn't it just be easier if you gave me commit rights?

Not really. Whether or not you have commit rights, you need to go through nearly all of these steps. This process is the standard process that most open source projects use to accept code from new contributors.

We will consider giving contributors commit rights after they have demonstrated their ability to follow this procedure. Watir committers also need to be able to accept and review patches from the community, hence the importance of understanding this process.

References

Tortoise SVN Client

Tortoise SVN is a third-party client for the Subversion version control system. Once Tortoise SVN is installed goto the location in Windows Explorer where Watir is to be installed and checkout from this location: http://svn.seleniumhq.org/svn/watir/trunk. When changes have been made select the working directory, right click and choose "TortoiseSVN > Create Patch" (don't forget your unit tests).

Eclipse

There is a Subversion Eclipse Plugin called: Subclipse . Instructions on how to submit a SVN patch using it are here .

Dr. Nic's Advice

Here is a good article that provides general advice on how to submit a patch for any open source project.