Why patches?

So... You've implemented a nice feature (or bug fix) in your local TWiki, 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

Here's how to produce a patch:

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 TWiki production release withut local changes.

diff -N will put into a diff any files that are deemed to be missing.

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.

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.

Make sure you say exactly what version of TWiki you patched.

if you made any other local changes to the TWiki source, please be careful to exclude them from your patch.

If you are fixing a bug, please attach the patch file to the bug report in Bugs web.

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 Codev.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 TWiki code is reasonably consistent overall, improving readability.

Testing

Make sure write the code so that is usable in the TWiki 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

Comments?

The details of producing patches could be improved, but context diff patches would be a great improvement so this is a reasonable first step. -- RD

Suggestion: start and close your changes with your initials and perhaps a reference to a twiki discussion topic. This way it will be easier to track down potential problems when multiple "after-market" patches have been applied. For example:

where 'after some time' is documented in the orange header on every topic in the Bugs web as "NOTE: Do not register here at develop.twiki.org, please use your twiki.org account to login (login works here after one hour of registration on twiki.org)."