diff --git a/PATCHES b/PATCHES index 9316a31a..314a363e 100644 --- a/PATCHES +++ b/PATCHES @@ -1,65 +1,95 @@ * Guidelines for patch submissions. =================================== +** What is a patch? +------------------- + +A patch file, also known as a "diff", is a textual representation of +changes to source code. Patches are readable enough to be reviewed by +humans and at the same time regular enough to be processed by +programs. The `patch' utility is used to change the source code in +the manner that the patch describes, this being called "applying" the +patch. Patches work even on files that have been modified +independently of the modifications in the patch, as long as those +other changes do not conflict with the patch. + +Because of these properties, patches are the preferred means of +distributing the changes to a free software project. If you have made +a change to Wget and would like to contribute it, you will need to +create a patch and send it to the developers; please read on. + ** Where to send the patches. ----------------------------- Patches intended to be applied to Wget should be mailed to . Each patch will be reviewed by the developers, and will be acked and added to the distribution, or -rejected with an explanation. +rejected with an explanation. Unfortunately, the developers are often +busy with their day jobs, so the review process can take a while. If you want to discuss your patch with the community of Wget users and -developers, it is OK to send it to the general list at -. If the patch is really huge (more than 100K or -so), you may want to put it on the web and post the URL. +developers, it is OK to send it to the main list at . +If the patch is really huge (more than 100K or so), you may want to +put it on the web and post the URL. EVERY patch should be accompanied by an explanation of what the patch -changes, and why the change is necessary. The explanation need not be -long, but please don't just send a patch without any text. +changes, and why the change is desirable or necessary. The +explanation need not be long, but please don't just send a patch +without any accompanying text. Normally, a patch can be just inserted into the message, after the explanation and the ChangeLog entry. However, if your mail composer -or gateway is inclined to munge patches, e.g. by line-wrapping them, +or gateway is inclined to munge patches, e.g. by wrapping long lines, please send them out as a MIME attachment. It is important that the -patch survives the travel so that we can feed it to the `patch' -utility after reviewing it. +patch survives the travel unchanged so that we can feed it to the +`patch' utility after reviewing it. ** How to create patches. ------------------------- -First, make sure you get the latest version of the source. This is -normally the latest release. If you're adding a new feature, or -changing the code in some major way, you might want to download the -latest sources from the CVS server. This procedure is described at -. +First, please make sure that you are working with the latest version +of the source -- changing obsolete code is a waste of time. Working +on the latest release is acceptable in most cases, but it is better +yet to download the very latest sources from the public CVS server and +work on those. The web page at explains +what CVS is and how to check out Wget's source code from the public +repository. -Patches are created using the `diff' utility. When making patches, +Patches are created using the `diff' program. When making patches, please use the `-u' option, or if your diff doesn't support it, `-c'. -Using ordinary (context-free) diffs are notoriously prone to error, -since line numbers tend to change when others make changes to the same +Ordinary (context-free) diffs are notoriously prone to errors, since +line numbers tend to change when others make changes to the same source file. -An example of the `diff' usage: +In the general case, `diff' is used like this: - diff -u OLDFILE NEWFILE - - -or- - - diff -c OLDFILE NEWFILE + diff -u ORIGFILE CHANGEDFILE > patch.txt Also, it is helpful if you create the patch in the top level of -the Wget source directory: +the Wget source directory. For example: - $ cp src/http.c src/http.c.orig - ...hack, hack, hack.... - $ diff -u src/http.c.orig src/http.c + cp src/http.c src/http.c.orig + ... modify src/http.c .... + diff -u src/http.c.orig src/http.c > patch.txt -If your patch changes more than one file, the output of all the diff -invocations should be concatenated to form a single patch. -Alternatively, you can use the `-r' option to compare entire -directories. If you do that, be careful not to include the -differences to automatically generated files, such as `.info*'. +If your patch changes more than one file, feel free to simply +concatenate the diffs of different files into a large diff: + + (diff -u foo.orig foo; diff -u bar.orig bar) > patch.txt + +The alternative is to leave the unchanged source lying around and use +the `-r' option to compare entire directories: + + diff -ru wget-1.9.orig wget-1.9 > patch.txt + +If you do that, please be careful not to include the differences to +automatically generated files, such as `.info*'. + +If you are using CVS, generating diffs is much simpler -- after +changing the files, all you need to do is run the following command +from Wget's top-level directory: + + cvs diff -u > patch.txt If you run on Windows and don't have `diff' handy, please get one. It's extremely hard to review changes to files unless they're in the @@ -80,12 +110,13 @@ Wget abides by the GNU coding standards, available at: http://www.gnu.org/prep/standards.html -To me the most important single point in that entire document is "no -arbitrary limits". Even when Wget's coding is less than exemplary, it -respects that rule. There should be no exceptions. +I consider perhaps the most important single point in that entire +document to be the "no arbitrary limits" rule. Even where Wget's +coding is less than exemplary, it respects that rule. There should be +no exceptions. Here is a short recap of the GNU formatting and naming conventions, -borrowed from XEmacs: +partly borrowed from XEmacs: * Put a space after every comma. @@ -120,11 +151,11 @@ borrowed from XEmacs: -------------------- Each patch should be accompanied by an update to the appropriate -ChangeLog file. Please don't mail patches to ChangeLog because they -have an extremely high rate of failure; just mail us the new part of -the ChangeLog you added. Patches without a ChangeLog entry will be -accepted, but this creates additional work for the maintainers, so -please do write the ChangeLog entries. +ChangeLog file. Please don't mail diffs of ChangeLog files because +they have an extremely high rate of failure; just mail us the new +entries you added to the ChangeLog. Patches without a ChangeLog entry +will be accepted, but this creates additional work for the +maintainers, so please do take the time to write one. Guidelines for writing ChangeLog entries are also governed by the GNU coding standards, under the "Change Logs" section.