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
==============================================================================
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.
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
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 git Repository
3.2 How To Make a Patch with git
- You need to first checkout the respository:
+ You need to first checkout the repository:
git clone git://github.com/bagder/curl.git
commit.
Now send those patches off to the curl-library list. You can of course opt to
- do that with the 'get send-email' command.
+ do that with the 'git send-email' command.
3.3 How To Make a Patch without git
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
- 1. Submit your patch to the curl-library mailing list
+ Submit your patch to the curl-library mailing list.
- 2. Make the patch against as recent sources as possible.
+ Make the patch against as recent sources as possible.
- 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.
+ 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.
- 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.
+ 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.
- 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.
+ 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.
+ 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.
+
+ We don't like that. We want them mailed for these reasons:
- ---- start ----
- [area]: [short line describing the main effect]
+ - Peer review. Anyone and everyone on the list can review, comment and
+ improve on the patch. Pull requests limit this ability.
- [separate the above single line from the rest with an empty line]
+ - 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.
- [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]
- ---- stop ----
+ - 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.
- 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
+ - Merges on github prevents rebases and even enforces --no-ff which is a git
+ style we don't otherwise use in the project
+ However: once patches have been reviewed and deemed fine on list they are
+ perfectly OK to be pulled from a published git tree.
projects / external / curl.git / blobdiff