Revert "Update to 7.44.0"
[platform/upstream/curl.git] / docs / CONTRIBUTE
index df161d7..83fa420 100644 (file)
  2.11 Test Cases
 
  3. Pushing Out Your Changes
- 3.1 Write Access to CVS Repository
- 3.2 How To Make a Patch
- 3.3 How to get your changes into the main sources
+ 3.1 Write Access to git Repository
+ 3.2 How To Make a Patch with git
+ 3.3 How To Make a Patch without git
+ 3.4 How to get your changes into the main sources
+ 3.5 Write good commit messages
+ 3.6 Please don't send pull requests
 
 ==============================================================================
 
@@ -76,9 +79,9 @@
 1.3 What To Read
 
  Source code, the man pages, the INTERNALS document, TODO, KNOWN_BUGS, the
- most recent CHANGES. Just lurking on the libcurl mailing list is gonna give
- you a lot of insights on what's going on right now. Asking there is a good
- idea too.
+ most recent CHANGES. Just lurking on the curl-library mailing list is gonna
+ give you a lot of insights on what's going on right now. Asking there is a
good idea too.
 
 2. cURL Coding Standards
 
 
 2.2 Indenting
 
Please try using the same indenting levels and bracing method as all the
- other code already does. It makes the source code a lot easier to follow if
- all of it is written using the same style. We don't ask you to like it, we
- just ask you to follow the tradition! ;-) This mainly means: 2-level indents,
- using spaces only (no tabs) and having the opening brace ({) on the same line
as the if() or while().
Use the same indenting levels and bracing method as all the other code
+ already does. It makes the source code easier to follow if all of it is
+ written using the same style. We don't ask you to like it, we just ask you to
+ follow the tradition! ;-) This mainly means: 2-level indents, using spaces
+ only (no tabs) and having the opening brace ({) on the same line as the if()
+ or while().
 
  Also note that we use if() and while() with no space before the parenthesis.
 
 
 2.4 Line Lengths
 
- We try to keep source lines shorter than 80 columns.
+ We write source lines shorter than 80 columns.
 
 2.5 General Style
 
  description exactly what they correct so that all patches can be selectively
  applied by the maintainer or other interested parties.
 
+ Also, separate patches enable bisecting much better when we track problems in
+ the future.
+
 2.9 Patch Against Recent Sources
 
  Please try to get the latest available sources to make your patches
  against. It makes the life of the developers so much easier. The very best is
- if you get the most up-to-date sources from the CVS repository, but the
+ if you get the most up-to-date sources from the git repository, but the
  latest release archive is quite OK as well!
 
 2.10 Document
  test case that verifies that it works as documented. If every submitter also
  posts a few test cases, it won't end up as a heavy burden on a single person!
 
+ If you don't have test cases or perhaps you have done something that is very
+ hard to write tests for, do explain exactly how you have otherwise tested and
+ verified your changes.
+
 3. Pushing Out Your Changes
 
-3.1 Write Access to CVS Repository
+3.1 Write Access to git Repository
 
  If you are a frequent contributor, or have another good reason, you can of
- course get write access to the CVS repository and then you'll be able to
- check-in all your changes straight into the CVS tree instead of sending all
- changes by mail as patches. Just ask if this is what you'd want. You will be
- required to have posted a few quality patches first, before you can be
- granted write access.
+ course get write access to the git repository and then you'll be able to push
+ your changes straight into the git repo instead of sending changes by mail as
+ patches. Just ask if this is what you'd want. You will be required to have
+ posted a few quality patches first, before you can be granted push access.
+
+3.2 How To Make a Patch with git
+
+ You need to first checkout the repository:
+
+     git clone git://github.com/bagder/curl.git
+
+ You then proceed and edit all the files you like and you commit them to your
+ local repository:
+
+     git commit [file]
 
-3.2 How To Make a Patch
+ As usual, group your commits so that you commit all changes that at once that
+ constitutes a logical change. See also section "3.5 Write good commit
+ messages".
+
+ Once you have done all your commits and you're happy with what you see, you
+ can make patches out of your changes that are suitable for mailing:
+
+     git format-patch remotes/origin/master
+
+ This creates files in your local directory named NNNN-[name].patch for each
+ commit.
+
+ Now send those patches off to the curl-library list. You can of course opt to
+ do that with the 'git send-email' command.
+
+3.3 How To Make a Patch without git
 
  Keep a copy of the unmodified curl sources. Make your changes in a separate
  source tree. When you think you have something that you want to offer the
 
  For unix-like operating systems:
 
-   http://www.gnu.org/software/patch/patch.html
-   http://www.gnu.org/directory/diffutils.html
+     http://www.gnu.org/software/patch/patch.html
+     http://www.gnu.org/directory/diffutils.html
 
  For Windows:
 
-   http://gnuwin32.sourceforge.net/packages/patch.htm
-   http://gnuwin32.sourceforge.net/packages/diffutils.htm
+     http://gnuwin32.sourceforge.net/packages/patch.htm
+     http://gnuwin32.sourceforge.net/packages/diffutils.htm
+
+3.4 How to get your changes into the main sources
+
+ Submit your patch to the curl-library mailing list.
+
+ Make the patch against as recent sources as possible.
+
+ Make sure your patch adheres to the source indent and coding style of already
+ existing source code. Failing to do so just adds more work for me.
+
+ Respond to replies on the list about the patch and answer questions and/or
+ fix nits/flaws. This is very important. I will take lack of replies as a sign
+ that you're not very anxious to get your patch accepted and I tend to simply
+ drop such patches from my TODO list.
+
+ If you've followed the above paragraphs and your patch still hasn't been
+ incorporated after some weeks, consider resubmitting it to the list.
+
+3.5 Write good commit messages
+
+ A short guide to how to do fine commit messages in the curl project.
+
+      ---- start ----
+      [area]: [short line describing the main effect]
+
+      [separate the above single line from the rest with an empty line]
+
+      [full description, no wider than 72 columns that describe as much as
+      possible as to why this change is made, and possibly what things
+      it fixes and everything else that is related]
+
+      [Bug: link to source of the report or more related discussion]
+      [Reported-by: John Doe - credit the reporter]
+      [whatever-else-by: credit all helpers, finders, doers]
+      ---- stop ----
+
+ Don't forget to use commit --author="" if you commit someone else's work,
+ and make sure that you have your own user and email setup correctly in git
+ before you commit
+
+3.6 Please don't send pull requests
+
+ With git (and especially github) it is easy and tempting to send a pull
+ request to one or more people in the curl project to have changes merged this
+ way instead of mailing patches to the curl-library mailing list.
 
-3.3 How to get your changes into the main sources
+ We don't like that. We want them mailed for these reasons:
 
- 1. Submit your patch to the curl-library mailing list
+ - Peer review. Anyone and everyone on the list can review, comment and
+   improve on the patch. Pull requests limit this ability.
 
- 2. Make the patch against as recent sources as possible.
+ - Anyone can merge the patch into their own trees for testing and those who
+   have push rights can push it to the main repo. It doesn't have to be anyone
+   the patch author knows beforehand.
 
- 3. Make sure your patch adheres to the source indent and coding style of
-    already existing source code. Failing to do so just adds more work for me.
+ - Commit messages can be tweaked and changed if merged locally instead of
+   using github. Merges directly on github requires the changes to be perfect
+   already, which they seldom are.
 
- 4. Respond to replies on the list about the patch and answer questions and/or
-    fix nits/flaws. This is very important. I will take lack of replies as a
-    sign that you're not very anxious to get your patch accepted and I tend to
-    simply drop such patches from my TODO list.
+ - Merges on github prevents rebases and even enforces --no-ff which is a git
+   style we don't otherwise use in the project
 
- 5. If you've followed the above mentioned paragraphs and your patch still
-    hasn't been incorporated after some weeks, consider resubmitting it to the
-    list.
+ However: once patches have been reviewed and deemed fine on list they are
+ perfectly OK to be pulled from a published git tree.