docs/CONTRIBUTE

   1                                   _   _ ____  _
   2                               ___| | | |  _ \| |
   3                              / __| | | | |_) | |
   4                             | (__| |_| |  _ <| |___
   5                              \___|\___/|_| \_\_____|
   6
   7                         When Contributing Source Code
   8
   9  This document is intended to offer guidelines that can be useful to keep in
  10  mind when you decide to contribute to the project. This concerns new features
  11  as well as corrections to existing flaws or bugs.
  12
  13  1. Learning cURL
  14  1.1 Join the Community
  15  1.2 License
  16  1.3 What To Read
  17
  18  2. Write a good patch
  19  2.1 Follow code style
  20  2.2 Non-clobbering All Over
  21  2.3 Write Separate Patches
  22  2.4 Patch Against Recent Sources
  23  2.5 Document
  24  2.6 Test Cases
  25
  26  3. Pushing Out Your Changes
  27  3.1 Write Access to git Repository
  28  3.2 How To Make a Patch with git
  29  3.3 How To Make a Patch without git
  30  3.4 How to get your changes into the main sources
  31  3.5 Write good commit messages
  32  3.6 About pull requests
  33
  34 ==============================================================================
  35
  36 1. Learning cURL
  37
  38 1.1 Join the Community
  39
  40  Skip over to https://curl.haxx.se/mail/ and join the appropriate mailing
  41  list(s).  Read up on details before you post questions. Read this file before
  42  you start sending patches! We prefer patches and discussions being held on
  43  the mailing list(s), not sent to individuals.
  44
  45  Before posting to one of the curl mailing lists, please read up on the mailing
  46  list etiquette: https://curl.haxx.se/mail/etiquette.html
  47
  48  We also hang out on IRC in #curl on irc.freenode.net
  49
  50  If you're at all interested in the code side of things, consider clicking
  51  'watch' on the curl repo at github to get notified on pull requests and new
  52  issues posted there.
  53
  54 1.2. License
  55
  56  When contributing with code, you agree to put your changes and new code under
  57  the same license curl and libcurl is already using unless stated and agreed
  58  otherwise.
  59
  60  If you add a larger piece of code, you can opt to make that file or set of
  61  files to use a different license as long as they don't enforce any changes to
  62  the rest of the package and they make sense. Such "separate parts" can not be
  63  GPL licensed (as we don't want copyleft to affect users of libcurl) but they
  64  must use "GPL compatible" licenses (as we want to allow users to use libcurl
  65  properly in GPL licensed environments).
  66
  67  When changing existing source code, you do not alter the copyright of the
  68  original file(s). The copyright will still be owned by the original
  69  creator(s) or those who have been assigned copyright by the original
  70  author(s).
  71
  72  By submitting a patch to the curl project, you are assumed to have the right
  73  to the code and to be allowed by your employer or whatever to hand over that
  74  patch/code to us. We will credit you for your changes as far as possible, to
  75  give credit but also to keep a trace back to who made what changes. Please
  76  always provide us with your full real name when contributing!
  77
  78 1.3 What To Read
  79
  80  Source code, the man pages, the INTERNALS document, TODO, KNOWN_BUGS and the
  81  most recent changes in the git log. Just lurking on the curl-library mailing
  82  list is gonna give you a lot of insights on what's going on right now. Asking
  83  there is a good idea too.
  84
  85 2. Write a good patch
  86
  87 2.1 Follow code style
  88
  89  When writing C code, follow the CODE_STYLE already established in the
  90  project. Consistent style makes code easier to read and mistakes less likely
  91  to happen.
  92
  93 2.2 Non-clobbering All Over
  94
  95  When you write new functionality or fix bugs, it is important that you don't
  96  fiddle all over the source files and functions. Remember that it is likely
  97  that other people have done changes in the same source files as you have and
  98  possibly even in the same functions. If you bring completely new
  99  functionality, try writing it in a new source file. If you fix bugs, try to
 100  fix one bug at a time and send them as separate patches.
 101
 102 2.3 Write Separate Patches
 103
 104  It is annoying when you get a huge patch from someone that is said to fix 511
 105  odd problems, but discussions and opinions don't agree with 510 of them - or
 106  509 of them were already fixed in a different way. Then the patcher needs to
 107  extract the single interesting patch from somewhere within the huge pile of
 108  source, and that gives a lot of extra work. Preferably, all fixes that
 109  correct different problems should be in their own patch with an attached
 110  description exactly what they correct so that all patches can be selectively
 111  applied by the maintainer or other interested parties.
 112
 113  Also, separate patches enable bisecting much better when we track problems in
 114  the future.
 115
 116 2.4 Patch Against Recent Sources
 117
 118  Please try to get the latest available sources to make your patches
 119  against. It makes the life of the developers so much easier. The very best is
 120  if you get the most up-to-date sources from the git repository, but the
 121  latest release archive is quite OK as well!
 122
 123 2.5 Document
 124
 125  Writing docs is dead boring and one of the big problems with many open source
 126  projects. Someone's gotta do it. It makes it a lot easier if you submit a
 127  small description of your fix or your new features with every contribution so
 128  that it can be swiftly added to the package documentation.
 129
 130  The documentation is always made in man pages (nroff formatted) or plain
 131  ASCII files. All HTML files on the web site and in the release archives are
 132  generated from the nroff/ASCII versions.
 133
 134 2.6 Test Cases
 135
 136  Since the introduction of the test suite, we can quickly verify that the main
 137  features are working as they're supposed to. To maintain this situation and
 138  improve it, all new features and functions that are added need to be tested
 139  in the test suite. Every feature that is added should get at least one valid
 140  test case that verifies that it works as documented. If every submitter also
 141  posts a few test cases, it won't end up as a heavy burden on a single person!
 142
 143  If you don't have test cases or perhaps you have done something that is very
 144  hard to write tests for, do explain exactly how you have otherwise tested and
 145  verified your changes.
 146
 147 3. Pushing Out Your Changes
 148
 149 3.1 Write Access to git Repository
 150
 151  If you are a frequent contributor, or have another good reason, you can of
 152  course get write access to the git repository and then you'll be able to push
 153  your changes straight into the git repo instead of sending changes by mail as
 154  patches. Just ask if this is what you'd want. You will be required to have
 155  posted a few quality patches first, before you can be granted push access.
 156
 157 3.2 How To Make a Patch with git
 158
 159  You need to first checkout the repository:
 160
 161      git clone https://github.com/curl/curl.git
 162
 163  You then proceed and edit all the files you like and you commit them to your
 164  local repository:
 165
 166      git commit [file]
 167
 168  As usual, group your commits so that you commit all changes that at once that
 169  constitutes a logical change. See also section "3.5 Write good commit
 170  messages".
 171
 172  Once you have done all your commits and you're happy with what you see, you
 173  can make patches out of your changes that are suitable for mailing:
 174
 175      git format-patch remotes/origin/master
 176
 177  This creates files in your local directory named NNNN-[name].patch for each
 178  commit.
 179
 180  Now send those patches off to the curl-library list. You can of course opt to
 181  do that with the 'git send-email' command.
 182
 183 3.3 How To Make a Patch without git
 184
 185  Keep a copy of the unmodified curl sources. Make your changes in a separate
 186  source tree. When you think you have something that you want to offer the
 187  curl community, use GNU diff to generate patches.
 188
 189  If you have modified a single file, try something like:
 190
 191      diff -u unmodified-file.c my-changed-one.c > my-fixes.diff
 192
 193  If you have modified several files, possibly in different directories, you
 194  can use diff recursively:
 195
 196      diff -ur curl-original-dir curl-modified-sources-dir > my-fixes.diff
 197
 198  The GNU diff and GNU patch tools exist for virtually all platforms, including
 199  all kinds of Unixes and Windows:
 200
 201  For unix-like operating systems:
 202
 203      https://savannah.gnu.org/projects/patch/
 204      https://www.gnu.org/software/diffutils/
 205
 206  For Windows:
 207
 208      http://gnuwin32.sourceforge.net/packages/patch.htm
 209      http://gnuwin32.sourceforge.net/packages/diffutils.htm
 210
 211 3.4 How to get your changes into the main sources
 212
 213  Submit your patch to the curl-library mailing list.
 214
 215  Make the patch against as recent sources as possible.
 216
 217  Make sure your patch adheres to the source indent and coding style of already
 218  existing source code. Failing to do so just adds more work for me.
 219
 220  Respond to replies on the list about the patch and answer questions and/or
 221  fix nits/flaws. This is very important. I will take lack of replies as a sign
 222  that you're not very anxious to get your patch accepted and I tend to simply
 223  drop such patches from my TODO list.
 224
 225  If you've followed the above paragraphs and your patch still hasn't been
 226  incorporated after some weeks, consider resubmitting it to the list.
 227
 228 3.5 Write good commit messages
 229
 230  A short guide to how to do fine commit messages in the curl project.
 231
 232       ---- start ----
 233       [area]: [short line describing the main effect]
 234
 235       [separate the above single line from the rest with an empty line]
 236
 237       [full description, no wider than 72 columns that describe as much as
 238       possible as to why this change is made, and possibly what things
 239       it fixes and everything else that is related]
 240
 241       [Bug: link to source of the report or more related discussion]
 242       [Reported-by: John Doe - credit the reporter]
 243       [whatever-else-by: credit all helpers, finders, doers]
 244       ---- stop ----
 245
 246  Don't forget to use commit --author="" if you commit someone else's work,
 247  and make sure that you have your own user and email setup correctly in git
 248  before you commit
 249
 250 3.6 About pull requests
 251
 252  With git (and especially github) it is easy and tempting to send a pull
 253  request to the curl project to have changes merged this way instead of
 254  mailing patches to the curl-library mailing list.
 255
 256  We used to dislike this but we're trying to change that and accept that this
 257  is a frictionless way for people to contribute to the project. We now welcome
 258  pull requests!
 259
 260  We will continue to avoid using github's merge tools to make the history
 261  linear and to make sure commits follow our style guidelines.