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 bug-wget@gnu.org. Each patch will be reviewed by the developers, and will be acked and added to the distribution, or rejected with an explanation. Unfortunately, the developers are often busy with their day jobs, so the review process can take a while.

Every patch should be accompanied by an explanation of what the patch 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 wrapping long lines, please send them out as a MIME attachment. It is important that the patch survives the travel unchanged so that we can feed it to the `patch' utility after reviewing it.

How to create patches with Mercurial

If you download Mercurial, you can pull down a clone of the Wget source repository (RepositoryAccess).

Then, as you make changes, you can check in your work locally as you're working on it. When you're ready to submit it, you can use hg export or the patchbomb extension (hg email) to send the patches.

For example:

$ hg clone http://hg.addictivecode.org/wget/mainline wget
$ cd wget
  ( ... make various changes ...)
$ hg ci -m 'Implement really cool feature'
  ( ... perhaps more changes, and more "hg ci"s ... )
$ hg export start-revision:end-revision > foo.patch
  ( ... send contents of foo.patch, along with description and
        changelog entry, to mailing list ...)

See UsingMercurial for more information on using Mercurial to hack on GNU Wget, including other ways to get your changes into the public repositories.

How to create patches without Mercurial

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 Mercurial server and work on those. The web page at RepositoryAccess explains how to get the source code from the repository.

Patches are created using the diff program. When making patches, please use the -u option, or if your diff doesn't support it, -c. Ordinary (context-free) diffs are notoriously prone to errors, since line numbers tend to change when others make changes to the same source file.

In the general case, diff is used like this:

diff -u ORIGFILE CHANGEDFILE > patch.txt

Also, it is helpful if you create the patch in the top level of the Wget source directory. For example:

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, 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 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 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 might not make sense. In that case, just attach the files along with an explanation of what is being changed.

Standards and coding style

Wget abides by the GNU coding standards, available at:

• http://www.gnu.org/prep/standards.html

I consider perhaps the most important single point in that entire document to be the "no arbitrary limits" rule.

Here is a short recap of the GNU formatting and naming conventions, partly borrowed from XEmacs:

• Put a space after every comma.

• Put a space before the parenthesis that begins a function call, macro call, function declaration or definition, or control statement (if, while, switch, for). (do not do this for macro definitions; this is invalid preprocessor syntax.)

• The brace that begins a control statement (if, while, switch, for) or a function definition should go on a line by itself.

• In function definitions, put the return type and all other qualifiers on a line before the function name. Thus, the function name is always at the beginning of a line.

• Indentation level is two spaces. (However, the first and following statements of a while/for/if/etc. block are indented four spaces from the while/for/if keyword. The opening and closing braces are indented two spaces.)

• Variable and function names should be all lowercase, with underscores separating words, except for a prefixing tag, which may be in uppercase. Do not use the mixed-case convention (e.g. SetVariableToValue ()) and especially do not use Microsoft Hungarian notation (char **rgszRedundantTag).

• Preprocessor constants and enumerations should be all uppercase, and should be prefixed with a tag that groups related constants together.

ChangeLog policy

Each patch should be accompanied by an update to the appropriate ChangeLog file. 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.