CrimsonFields - Creating Patches

What is a patch?

A path is a textual representation of the differences in two versions of the same file(s). They allow a developer to quickly see the modifications that have been made. Sending patches instead of the complete modified files also makes applying those changes to the source code much easier for the maintainers, especially if other changes have ben made in the mean time.

Suppose you download version 1.0 of Crimson Fields. You discover that it lacks a Klingon translation, so you decide to add one. Among other things you need to add bits to the unit set description. You update the respective file and send it back to the maintainer who could just replace the current file with your version, because, well, it's more up-to-date, right? It might be, but then again, it might not. Suppose that, two days before you did, someone else downloaded the same files and found it lacking an Eldarin translation. He modified the unit set and sent it to the developers who put it in their repository. Now, if they would just replace the unit set file again, they would lose all the changes made between the 1.0 release and the time they replace the file. Eldarin would stay a dead language. Using patches gets rid of this problem, because the Eldar can modify the Eldarin parts while the Klingons can modify the Klingon parts without interfering with each other (mostly, anyway).

How do I create a patch?

Patches are created using the diff utility which should exist for all platforms out there. Calling

diff -urNp file.old file.new >mypatch.diff

will create a patch containing all the differences between file.old and file.new (see below for the meaning of the parameters). Such a patch can be applied using the patch utility like this

patch <mypatch.diff

For further information about diff and patch please refer to the appropriate documentation.

Is there anything else I should consider when creating patches?

Definitely. The following guidelines are much appreciated by the developers.

Use unified diffs (the -u parameter to diff). This uses a different text format which is much easier to read by humans.
Create a separate patch for each logical change. For example, if your modifications include both a bug fix and the addition of a new feature, create one patch for each.
Do NOT create a separate patch for each file as long as the modifications belong to the same logical change. For example, if you add a new language (for which you need to touch several files), group all those changes into a single patch (use the -r parameter to diff to recursively diff entire directories and use -N to include any new files you added to the sources, e.g. diff -urNp ../crimson-1.0/ ./). You could also create several individual patches and simply string them together into one file. It is, however, important that all individual patches be created from the same base directory, preferably the project's root directory.
Test your patch. After creating your patch with diff, apply it to the original sources and check whether it still works as intended.
And last but not least: Document your changes. Describe what you are doing and why, even if it seems obvious to you.

Thanks for listening. We are looking forward to your contributions.

PHP Warnings

lib/pear/DB/common.php:741: Notice[8]: Only variable references should be returned by reference

lib/WikiUser.php:59: Notice[8]: Only variables should be assigned by reference

lib/pear/DB/common.php:741: Notice[8]: Only variable references should be returned by reference

lib/Template.php:112: Notice[8]: Only variables should be assigned by reference

lib/Template.php:114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'body') (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'body') (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'top') (In template 'body') (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'top') (In template 'body') (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/pear/DB/common.php (In template 'navbar') (In template 'top') (In template 'body') (In template 'html'):741: Notice[8]: Only variable references should be returned by reference

lib/Template.php (In template 'body') (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'body') (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'browse') (In template 'body') (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'browse') (In template 'body') (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'browse-footer') (In template 'browse') (In template 'body') (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'browse-footer') (In template 'browse') (In template 'body') (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'actionbar') (In template 'browse-footer') (In template 'browse') (In template 'body') (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'actionbar') (In template 'browse-footer') (In template 'browse') (In template 'body') (In template 'html'):114: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'body') (In template 'html'):112: Notice[8]: Only variables should be assigned by reference

lib/Template.php (In template 'body') (In template 'html'):114: Notice[8]: Only variables should be assigned by reference