sjero.net Git - wget/blob - PATCHES

   1 * Guidelines for patch submissions.
   2 ===================================
   3
   4 ** What is a patch?
   5 -------------------
   6
   7 A patch file, also known as a "diff", is a textual representation of
   8 changes to source code.  Patches are readable enough to be reviewed by
   9 humans and at the same time regular enough to be processed by
  10 programs.  The `patch' utility is used to change the source code in
  11 the manner that the patch describes, this being called "applying" the
  12 patch.  Patches work even on files that have been modified
  13 independently of the modifications in the patch, as long as those
  14 other changes do not conflict with the patch.
  15
  16 Because of these properties, patches are the preferred means of
  17 distributing the changes to a free software project.  If you have made
  18 a change to Wget and would like to contribute it, you will need to
  19 create a patch and send it to the developers; please read on.
  20
  21 ** Where to send the patches.
  22 -----------------------------
  23
  24 Patches intended to be applied to Wget should be mailed to
  25 <wget-patches@sunsite.dk>.  Each patch will be reviewed by the
  26 developers, and will be acked and added to the distribution, or
  27 rejected with an explanation.  Unfortunately, the developers are often
  28 busy with their day jobs, so the review process can take a while.
  29
  30 If you want to discuss your patch with the community of Wget users and
  31 developers, it is OK to send it to the main list at <wget@sunsite.dk>.
  32 If the patch is really huge (more than 100K or so), you may want to
  33 put it on the web and post the URL.
  34
  35 EVERY patch should be accompanied by an explanation of what the patch
  36 changes, and why the change is desirable or necessary.  The
  37 explanation need not be long, but please don't just send a patch
  38 without any accompanying text.
  39
  40 Normally, a patch can be just inserted into the message, after the
  41 explanation and the ChangeLog entry.  However, if your mail composer
  42 or gateway is inclined to munge patches, e.g. by wrapping long lines,
  43 please send them out as a MIME attachment.  It is important that the
  44 patch survives the travel unchanged so that we can feed it to the
  45 `patch' utility after reviewing it.
  46
  47 ** How to create patches.
  48 -------------------------
  49
  50 First, please make sure that you are working with the latest version
  51 of the source -- changing obsolete code is a waste of time.  Working
  52 on the latest release is acceptable in most cases, but it is better
  53 yet to download the very latest sources from the public CVS server and
  54 work on those.  The web page at <http://sunsite.dk/wget/> explains
  55 what CVS is and how to check out Wget's source code from the public
  56 repository.
  57
  58 Patches are created using the `diff' program.  When making patches,
  59 please use the `-u' option, or if your diff doesn't support it, `-c'.
  60 Ordinary (context-free) diffs are notoriously prone to errors, since
  61 line numbers tend to change when others make changes to the same
  62 source file.
  63
  64 In the general case, `diff' is used like this:
  65
  66     diff -u ORIGFILE CHANGEDFILE > patch.txt
  67
  68 Also, it is helpful if you create the patch in the top level of
  69 the Wget source directory.  For example:
  70
  71     cp src/http.c src/http.c.orig
  72     ... modify src/http.c ....
  73     diff -u src/http.c.orig src/http.c > patch.txt
  74
  75 If your patch changes more than one file, feel free to simply
  76 concatenate the diffs of different files into a large diff:
  77
  78     (diff -u foo.orig foo; diff -u bar.orig bar) > patch.txt
  79
  80 The alternative is to leave the unchanged source lying around and use
  81 the `-r' option to compare entire directories:
  82
  83     diff -ru wget-1.9.orig wget-1.9 > patch.txt
  84
  85 If you do that, please be careful not to include the differences to
  86 automatically generated files, such as `.info*'.
  87
  88 If you are using CVS, generating diffs is much simpler -- after
  89 changing the files, all you need to do is run the following command
  90 from Wget's top-level directory:
  91
  92     cvs diff -u > patch.txt
  93
  94 If you run on Windows and don't have `diff' handy, please get one.
  95 It's extremely hard to review changes to files unless they're in the
  96 form of a patch.  If you really cannot use a variant of `diff', then
  97 mail us the whole new file and specify which version of Wget you
  98 changed; that way we will be able to generate the diff ourselves.
  99
 100 Finally, if your changes introduce new files, or if they change the
 101 old files past all recognition (e.g. by completely reimplementing the
 102 old stuff), sending a patch obviously doesn't make sense.  In that
 103 case, just attach the files along with an explanation of what is being
 104 changed.
 105
 106 ** Standards and coding style.
 107 ------------------------------
 108
 109 Wget abides by the GNU coding standards, available at:
 110
 111     http://www.gnu.org/prep/standards.html
 112
 113 I consider perhaps the most important single point in that entire
 114 document to be the "no arbitrary limits" rule.  Even where Wget's
 115 coding is less than exemplary, it respects that rule.  There should be
 116 no exceptions.
 117
 118 Here is a short recap of the GNU formatting and naming conventions,
 119 partly borrowed from XEmacs:
 120
 121   * Put a space after every comma.
 122
 123   * Put a space before the parenthesis that begins a function call,
 124     macro call, function declaration or definition, or control
 125     statement (if, while, switch, for).  (DO NOT do this for macro
 126     definitions; this is invalid preprocessor syntax.)
 127
 128   * The brace that begins a control statement (if, while, for, switch,
 129     do) or a function definition should go on a line by itself.
 130
 131   * In function definitions, put the return type and all other
 132     qualifiers on a line before the function name.  Thus, the function
 133     name is always at the beginning of a line.
 134
 135   * Indentation level is two spaces.  (However, the first and
 136     following statements of a while/for/if/etc. block are indented
 137     four spaces from the while/for/if keyword.  The opening and
 138     closing braces are indented two spaces.)
 139
 140   * Variable and function names should be all lowercase, with
 141     underscores separating words, except for a prefixing tag, which may
 142     be in uppercase.  Do not use the mixed-case convention (e.g.
 143     SetVariableToValue ()) and *especially* do not use Microsoft
 144     Hungarian notation (char **rgszRedundantTag).
 145
 146   * Preprocessor constants and enumerations should be all uppercase,
 147     and should be prefixed with a tag that groups related constants
 148     together.
 149
 150 ** ChangeLog policy.
 151 --------------------
 152
 153 Each patch should be accompanied by an update to the appropriate
 154 ChangeLog file.  Please don't mail diffs of ChangeLog files because
 155 they have an extremely high rate of failure; just mail us the new
 156 entries you added to the ChangeLog.  Patches without a ChangeLog entry
 157 will be accepted, but this creates additional work for the
 158 maintainers, so please do take the time to write one.
 159
 160 Guidelines for writing ChangeLog entries are also governed by the GNU
 161 coding standards, under the "Change Logs" section.