= How to apply software patches =

Check out the CytoscapePatchSubmission page for detailed instructions on how to create patch files.

Before you do anything, '''READ THE PATCH'''.   Patches may seem simple, but they are notoriously hard to get right.  People frequently include inadvertant changes, make the patch against old versions of code, or inadvertantly delete code.  You should examine as much of the patch as possible before applying it. Some patches are so large that this is not always practical.  In these cases, consider applying the patch and then comparing the new code with the old code using diff tools (e.g. sdiff).  

If a patch doesn't include unit tests for the new functionality, you should be very careful with the patch.  Consider returning the patch and asking for updated tests.

== Using command line tools ==

The tool used to apply patches is called '''patch'''. Type '''man patch''' for specific invocation details.  The most important thing to understand about patches is that they need to be applied relative to where they were created. The patch command allows you to adjust the patch so that it matches your environment.  The general process for applying a patch is as follows:

 1. {{{cd /your/source/directory}}}
 1. put the patch file (new_code.patch) in the current directory.
 1. {{{patch -pX < new_code.patch}}}
 
The difficulty with patches lies in the '''-pX''' portion of the command.  The '''X''' represents a digit and the digit tells you how many directories to strip off of the patch so that the patch becomes relative to your directory.  

=== Example ===
An example may help explain things. Consider the patch below, called new.patch, that adds a new method '''newMethod()''' to the '''Cytoscape.java''' file.

{{{
Index: src/cytoscape/Cytoscape.java
===================================================================
RCS file: /common/cvsdir5/cytoscape/src/cytoscape/Cytoscape.java,v
retrieving revision 1.129
diff -u -r1.129 Cytoscape.java
--- src/cytoscape/Cytoscape.java        24 May 2006 17:55:29 -0000      1.129
+++ src/cytoscape/Cytoscape.java        31 May 2006 01:15:59 -0000
@@ -1751,6 +1751,14 @@
                return sessionState;
        }

+
+       /**
+        * My new method.
+        */
+       public void newMethod() {
+               // do important things here
+       }
+
        /**
         * Clear all networks and attributes and start a
         * new session.
}}}

We'll assume that your working directory is {{{/home/yourid/cytoscape}}}.  

'''Option #1''' is to copy the patch file into your {{{/home/yourid/cytoscape}}}
directory and run the command 
  
  {{{patch -p0 < new.patch}}}.  

The '''-p0''' indicates that no directories are stripped from the diff header which is this line:

{{{
Index: src/cytoscape/Cytoscape.java
}}}

You strip no directories because relative to your current directory {{{/home/yourid/cytoscape}}} the file Cytoscape.java that will be patched can be found in the {{{src/cytoscape}}} subdirectory.  This patch was made from the {{{/home/theirid/cytoscape}}} directory, the patch sender's equivalent of yours, so you don't need to strip any directories.

'''Option #2''' Assume that you've now copied the file to {{{/home/yourid/cytoscape/src/cytoscape}}} because you know that the patch is only for the file Cytoscape.java.  In this case, the command you would run is:

  {{{patch -p2 < new.patch}}} 

The '''-p2''' indicates that 2 directories are to be stripped.  Because the patch was made in directory {{{/home/theirid/cytoscape}}}, but you are in {{{/home/yourid/cytoscape/src/cytoscape}}}, the header of the patch no longer accurately represents the location of the file relative to your current location.  This means you need to strip off the {{{src/cytoscape}}} from the header so that the patch is once again correct relative to your current directory.


== Using Eclipse ==

People really use eclipse?  :)

== Once the patch is applied ==

'''''Very Important:  Make sure that you test the patch!!'''''   As noted above, it can be a challenge to get patches right, particularly if people are working from different types of codebases (e.g. a cvs checkout vs. a source distribution). Begin by reading the patch and evaluating what the differences are.  It is often very helpful to view the patched code side-by-side with the original code using a diff tool.  Once you're comfortable with the changes, test the patch thoroughly and check the new code in.