Patch Guidelines

The Foswiki developers produce patches every so often to correct problems in Foswiki. but that's not the only use of patching; you can use patches to contribute back to Foswiki as well.

Why patches?

So... You've implemented a nice feature (or bug fix) in your local Foswiki, and would like to see it get into the core code, but you don't have checkin access. The first thing to consider is if this feature can be implemented as a Plugin . If not, then the best way to offer a change to the core code is to produce a 'patch' - a set of context diffs produced by the diff tool (preferably GNU diff). This is much better than providing the modified files, because:

• Patches are easier to review than complete files, since they include only your changes and are plain text
• Patches are easy to apply to the sources in the Subversion repository
• Patches are small
• Patches only contain the modifications, therefore, if you're lucky, your patch can still apply on the next version of Foswiki if the changes weren't too close to yours

Here's how to produce a patch:

1. Just do diff -c from the old file to the new file, and repeat for each file changed (unified diffs are fine as well, just use diff -u). Use a well-defined version, such as a Foswiki production release withut local changes.
2. diff -N will put into a diff any files that are deemed to be missing.
3. Once you have a set of patch files, concatenate them all into a single file and test your patch against the original set of files, using patch -i with suitable options.
4. If you are proposing an enhancement, then attach your patch to a suitable page in Codev, as a .patch or .diff file. Very small patches can be included inline in the page, but please include the full contents of the patch file to simplify applying it, and don't do this if there are any TAB characters used in indentation as this may not work well.
5. Make sure you say exactly what version of Foswiki you patched.
   • if you made any other local changes to the Foswiki source, please be careful to exclude them from your patch.
6. If you are fixing a bug, please attach the patch file to the bug report in Tasks web.

Patch tools for your platform

• On Linux, good versions of diff and patch are included.
• On Unix, you can get hold of GNU diff and patch quite easily, try FoswikiOnUnix for useful sites for your Unix variant, or just Google:diffutils and http://www.gnu.org/software/patch/patch.html GNU Patch.
• On Windows, just download CygWin and install the diffutils and patch packages using the setup tool.

Coding standards

Please read and apply all the advice on coding standards linked from the ReadmeFirst guidelines. Keeping to these, even on simple things such as indentation and variable naming, makes it much easier to incorporate your patch and ensures that Foswiki code is reasonably consistent overall, improving readability.

Testing

Make sure write the code so that is usable in the Foswiki core - i.e. it doesn't depend on your particular site's setup, and runs on (at least) Unix/Linux, and preferably Windows as well. If you have a subversion checkout area, run the unit tests and exercise the manual tests on your patched code.

How to apply a patch

See HowToApplyPatch