sjero.net Git - wget/blob - PATCHES

   1 * Guidelines for patch submissions.
   2 ===================================
   3
   4 ** Where to send the patches.
   5 -----------------------------
   6
   7 Patches intended to be applied to Wget should be mailed to
   8 <wget-patches@sunsite.dk>.  Each patch will be reviewed by the
   9 developers, and will be acked and added to the distribution, or
  10 rejected with an explanation.
  11
  12 If you want to discuss your patch with the community of Wget users and
  13 developers, it is OK to send it to the general list at
  14 <wget@sunsite.dk>.  If the patch is really huge (more than 100K or
  15 so), you may want to put it on the web and post the URL.
  16
  17 EVERY patch should be accompanied by an explanation of what the patch
  18 changes, and why the change is necessary.  The explanation need not be
  19 long, but please don't just send a patch without any text.
  20
  21 Normally, a patch can be just inserted into the message, after the
  22 explanation and the ChangeLog entry.  However, if your mail composer
  23 or gateway is inclined to munge patches, e.g. by line-wrapping them,
  24 please send them out as a MIME attachment.  It is important that the
  25 patch survives the travel so that we can feed it to the `patch'
  26 utility after reviewing it.
  27
  28 ** How to create patches.
  29 -------------------------
  30
  31 First, make sure you get the latest version of the source.  This is
  32 normally the latest release.  If you're adding a new feature, or
  33 changing the code in some major way, you might want to download the
  34 latest sources from the CVS server.  This procedure is described at
  35 <http://sunsite.dk/wget/>.
  36
  37 Patches are created using the `diff' utility.  When making patches,
  38 please use the `-u' option, or if your diff doesn't support it, `-c'.
  39 Using ordinary (context-free) diffs are notoriously prone to error,
  40 since line numbers tend to change when others make changes to the same
  41 source file.
  42
  43 An example of the `diff' usage:
  44
  45     diff -u OLDFILE NEWFILE
  46
  47     -or-
  48
  49     diff -c OLDFILE NEWFILE
  50
  51 Also, it is helpful if you create the patch in the top level of
  52 the Wget source directory:
  53
  54     $ cp src/http.c src/http.c.orig
  55     ...hack, hack, hack....
  56     $ diff -u src/http.c.orig src/http.c
  57
  58 If your patch changes more than one file, the output of all the diff
  59 invocations should be concatenated to form a single patch.
  60 Alternatively, you can use the `-r' option to compare entire
  61 directories.  If you do that, be careful not to include the
  62 differences to automatically generated files, such as `.info*'.
  63
  64 If you run on Windows and don't have `diff' handy, please get one.
  65 It's extremely hard to review changes to files unless they're in the
  66 form of a patch.  If you really cannot use a variant of `diff', then
  67 mail us the whole new file and specify which version of Wget you
  68 changed; that way we will be able to generate the diff ourselves.
  69
  70 Finally, if your changes introduce new files, or if they change the
  71 old files past all recognition (e.g. by completely reimplementing the
  72 old stuff), sending a patch obviously doesn't make sense.  In that
  73 case, just attach the files along with an explanation of what is being
  74 changed.
  75
  76 ** Standards and coding style.
  77 ------------------------------
  78
  79 Wget abides by the GNU coding standards, available at:
  80
  81     http://www.gnu.org/prep/standards.html
  82
  83 To me the most important single point in that entire document is "no
  84 arbitrary limits".  Even when Wget's coding is less than exemplary, it
  85 respects that rule.  There should be no exceptions.
  86
  87 Here is a short recap of the GNU formatting and naming conventions,
  88 borrowed from XEmacs:
  89
  90   * Put a space after every comma.
  91
  92   * Put a space before the parenthesis that begins a function call,
  93     macro call, function declaration or definition, or control
  94     statement (if, while, switch, for).  (DO NOT do this for macro
  95     definitions; this is invalid preprocessor syntax.)
  96
  97   * The brace that begins a control statement (if, while, for, switch,
  98     do) or a function definition should go on a line by itself.
  99
 100   * In function definitions, put the return type and all other
 101     qualifiers on a line before the function name.  Thus, the function
 102     name is always at the beginning of a line.
 103
 104   * Indentation level is two spaces.  (However, the first and
 105     following statements of a while/for/if/etc. block are indented
 106     four spaces from the while/for/if keyword.  The opening and
 107     closing braces are indented two spaces.)
 108
 109   * Variable and function names should be all lowercase, with
 110     underscores separating words, except for a prefixing tag, which may
 111     be in uppercase.  Do not use the mixed-case convention (e.g.
 112     SetVariableToValue ()) and *especially* do not use Microsoft
 113     Hungarian notation (char **rgszRedundantTag).
 114
 115   * Preprocessor constants and enumerations should be all uppercase,
 116     and should be prefixed with a tag that groups related constants
 117     together.
 118
 119 ** ChangeLog policy.
 120 --------------------
 121
 122 Each patch should be accompanied by an update to the appropriate
 123 ChangeLog file.  Please don't mail patches to ChangeLog because they
 124 have an extremely high rate of failure; just mail us the new part of
 125 the ChangeLog you added.  Patches without a ChangeLog entry will be
 126 accepted, but this creates additional work for the maintainers, so
 127 please do write the ChangeLog entries.
 128
 129 Guidelines for writing ChangeLog entries are also governed by the GNU
 130 coding standards, under the "Change Logs" section.