This document explains in detail how to create patches to the VR Juggler developers for reviewing and (hopefully) committing, and it provides pointers on what the best audience for your patch may be. The information presented is based on the method used by the UNIX diff(1) and patch(1) utilities because that is what CVS uses.
Rules for making contributions (see the section called “Rules for Contributions”)
CVS documentation
diff(1) man page
There are two ways to create a patch to the VR Juggler source: using a copy of the source code checked out from CVS or making a comparison against an unmodified copy of a file. The first way is more convenient, but the second method does not necessarily require CVS knowledge.
If you have checked out a copy of the VR Juggler source code and have been modifying the code in that tree, making a patch (big or small) is easy. (Refer to the CVS documentation for information on how to check out a copy of VR Juggler from the CVS repository.) You can edit the checked-out file(s) all you want without retaining a backup copy because you can always get an unmodified version from the repository.
Once your work is done and you are ready to create the patch, you want to use the cvs diff command to get the differences between the original version and your new work. This command is a capable of doing a lot more than just creating patches, but we will focus only on that aspect of it here. Assuming a shell that allows redirection of standard output to a file, the command should be used as follows to create the patch for a single file:
% cvs diff filename filename.patch
Since CVS knows about the entire repository, you can use cvs diff to make a larger patch of several files, a single directory, a subtree of the larger directory tree or the entire VR Juggler source tree. You should be careful to keep only related patches together in a single file. Examples of how to perform each of these operations follow.
Patching several files: You can of course use wildcard expansions here as supported by your shell.
% cvs diff filename1 filename2 ... patch
Patching all the files in a directory (either the current directory or some subdirectory of the whole VR Juggler source tree):
% cvs diff directory_name patch
Here, you can use `.' to represent the current directory as usual. If the directory you are patching contains subdirectories, CVS will recurse into those by default and perform the diff operation there as well. To prevent recursion, use the standard -l (local) CVS command option:
% cvs diff -l directory_name patch
Creating a patch against the entire VR Juggler source tree works just the same as the previous method except that is executed from the top-level directory of the source tree.
Instead of using CVS to get the source and make the comparison (which can be slow if your network connection to SourceForge is hurting), it is possible to make a patch the “old-fashioned way”. Before editing a file, however, make sure to save a backup copy of it. You need this for comparison once your modifications are complete. The common convention is to make a copy the old file with the same name and extra extension (for example, vjThread.cpp.orig). Once you are satisfied that your work is complete, use the diff(1) utility to create the patch as follows (assuming a shell that supports redirection of standard out to a file):
% diff [options] filename.orig filename filename.patch
This must be repeated for every modified file. Make sure that the original file always goes first.
A nice thing about the patch(1) utility is that it can extract multiple patches from a single file. Submitting a single file is certain to make the developers happier than dealing with individual patch files for every file you modified. (Of course, you should not just lump all your patches into one file if they are unrelated. Use common sense when creating the patch files, and everything will be fab.) Assuming a UNIX or UNIX-like shell with redirection and appending of files, there are two ways to combine individual patches into a single file:
Create a patch file and append subsequent patches to it:
% diff [options] filename1.orig filename1 $HOME/my.patch % diff [options] filename2.orig filename2 $HOME/my.patch % ...
If that does not suit you, you can use the simple yet powerful cat(1) command to concatenate all your distinct patch files into one big patch:
% diff [options] filename1.orig filename1 $HOME/filename1.patch % diff [options] filename2.orig filename2 $HOME/filename2.patch % ... % cat $HOME/filename1.patch $HOME/filename2.patch ... > my_big_patch
There are three styles of diffs that can be generated for use as patches: standard diff, unified diff and context diff. In the author's experience, unified diffs are the easiest to read, and standard diffs are the hardest to read. The following two pages from the enline VR Juggler CVS repository show how unified and context diffs look:
Unified diff between Revisions 1.259 and 1.260 of configure.in
Context diff between Revisions 1.259 and 1.260 of configure.in
We cannot generate fancy, colored diffs for use as patches unfortunately. It certainly is nice that cvsweb will do that, however.
To generate a unified diff, specify the option -u on the command line when running the diff command. To create a context diff, specify the -c option instead. To create a standard diff, give no options at all. These work with both the CVS diff command and the diff(1) utility. To always create a specific kind of diff by default with CVS, add the following line to your $HOME/.cvsrc file:
diff optionNow that you have made your patches, it's time to send them off to the VR Juggler developers with commit access so that they can review them, commit them and praise you for your fine efforts. Before reading this section, please be sure to have read the section called “Rules for Contributions”. Failing to follow these rules could result in your slow review and/or acceptance of your patches. What is presented here will repeat some of what is written in that document, but it is important to read both.
The method used to present your patches to the committers depends on what kind of patches you have made. As of this writing, the most common types of patches we would like to see and expect to see are as follows:
Bug fixes: VR Juggler is not free of bugs, and patches from users who fix bugs are very welcome
Feature enhancements: VR Juggler offers a lot of features to users, but some interfaces may be incomplete or could be further extended
Feature additions: VR Juggler needs more device drivers and abstractions useful to programmers who are developing VR applications every day
If your patch is accepted, you will be given proper credit in the commit log as follows:
Description of patch
Submitted by: Helpful User great.person@wonderful.netThis is probably the most common type of patch VR Juggler users will submit. The best way to submit a patch for a bug is to attach it to a bug report through SourceForge. Copies of bug reports are sent to vrjuggler-devel@lists.sourceforge.net where all subscribers of that list see them. The bug report will be assigned to a developer with commit access, and that person will take charge of reviewing your patch and any further communication with you, the helpful submitter.
Submitting an enhancement to existing code requires a little bit more work than submitting a bug report. If you are implementing part of an interface that is not yet finished (for example, a method that only prints out “Not implemented yet!”), you should submit a bug report as above but describe it as a feature enhancement in your report. If you are extending an interface, you should first submit your proposed changes (in a high-level format with some pseudocode if appropriate) to vrjuggler-devel@lists.sourceforge.net for discussion before doing any hard work making the changes. This will allow interested people to respond with feedback, questions or a short “Go for it!” message. Once your patches are ready, then you should submit them to the list for reviewing before an interested committer will take them and actually commit them.
Feature additions stand to be controversial if not presented properly. For example, if you want to submit a complex computational geometry algorithm implementation, you had better have a really good reason. The first step you should take is a high-level proposal to vrjuggler-devel@lists.sourceforge.net which will no doubt generate much good discussion among developers. This step is encouraged to find out if people are interested in seeing your features as a part of the core VR Juggler library or would prefer to see them as something written at a higher level using VR Juggler as a basis. No one wants to see talented people doing a lot of work only to have it rejected because it doesn't fit with the intended design and use of a given project. (This is not intended to discourage people from trying to extend the design of VR Juggler but instead to suggest that VR Juggler be used as a basis for more complex tools when appropriate.)
After your proposal has been refined and heartily accepted, it's time for you to get to work on making the changes. Periodic progress reports are helpful so that the developers know that you are still hard at work and have not given up for lack of time or resources. Posting developmental patches at key stages helps too because the patches can be tested by other developers who can then provide feedback and bug reports.
Once your changes are ready (or some stage of your changes is ready to be committed), post your triumphant message with the attached patches. After all the traffic generated because of your work, the committers will no doubt jump at the chance to commit your changes and make them available to the community of users.