* 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
-<wget-patches@sunsite.auc.dk>. Each patch will be reviewed by the
+<wget-patches@sunsite.dk>. 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
-<wget@sunsite.auc.dk>. 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 <wget@sunsite.dk>.
+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
-<http://sunsite.dk/wget/>.
+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 Subversionn
+server and work on those. The web page at
+<http://www.gnu.org/software/wget/> explains how to get the source
+code from the 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 ORIGFILE CHANGEDFILE > patch.txt
- diff -u OLDFILE NEWFILE
+Also, it is helpful if you create the patch in the top level of
+the Wget source directory. For example:
- -or-
+ cp src/http.c src/http.c.orig
+ ... modify src/http.c ....
+ diff -u src/http.c.orig src/http.c > patch.txt
- diff -c OLDFILE NEWFILE
+If your patch changes more than one file, feel free to simply
+concatenate the diffs of different files into a large diff:
-Also, it is helpful if you create the patch in the top level of
-the Wget source directory:
+ (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*'.
- $ cp src/http.c src/http.c.orig
- ...hack, hack, hack....
- $ diff -u src/http.c.orig src/http.c
+If you are using Subversion, generating diffs is even simpler -- after
+changing the files, all you need to do is run the following command
+from Wget's top-level directory:
-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*'.
+ svn diff > patch.txt
-If you run on Windows and don't have `diff' handy, please get one.
+If you run on Windows and don't have `diff' handy, please obtain it.
It's extremely hard to review changes to files unless they're in the
form of a patch. If you really cannot use a variant of `diff', then
-mail us the whole new file and specify which version of Wget you
+mail us the whole new file and indicate which version of Wget you
changed; that way we will be able to generate the diff ourselves.
Finally, if your changes introduce new files, or if they change the
old files past all recognition (e.g. by completely reimplementing the
-old stuff), sending a patch obviously doesn't make sense. In that
-case, just attach the files along with an explanation of what is being
-changed.
+old stuff), sending a patch might not make sense. In that case, just
+attach the files along with an explanation of what is being changed.
** Standards and coding style.
------------------------------
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.
--------------------
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.
projects / wget / blobdiff