diff options
Diffstat (limited to 'docs/CONTRIBUTE')
| -rw-r--r-- | docs/CONTRIBUTE | 105 |
1 files changed, 66 insertions, 39 deletions
diff --git a/docs/CONTRIBUTE b/docs/CONTRIBUTE index db03c42a..c6ea9773 100644 --- a/docs/CONTRIBUTE +++ b/docs/CONTRIBUTE @@ -34,6 +34,7 @@ 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 About pull requests ============================================================================== @@ -51,6 +52,10 @@ We also hang out on IRC in #curl on irc.freenode.net + If you're at all interested in the code side of things, consider clicking + 'watch' on the curl repo at github to get notified on pull requests and new + issues posted there. + 1.2. License When contributing with code, you agree to put your changes and new code under @@ -77,10 +82,10 @@ 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. + Source code, the man pages, the INTERNALS document, TODO, KNOWN_BUGS and the + most recent changes in the git log. 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 @@ -97,12 +102,12 @@ 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. @@ -150,6 +155,9 @@ 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 @@ -177,6 +185,10 @@ 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 @@ -189,9 +201,9 @@ 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 + git clone https://github.com/bagder/curl.git You then proceed and edit all the files you like and you commit them to your local repository: @@ -211,7 +223,7 @@ 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 @@ -233,47 +245,62 @@ For unix-like operating systems: - http://www.gnu.org/software/patch/patch.html - http://www.gnu.org/directory/diffutils.html + https://savannah.gnu.org/projects/patch/ + https://www.gnu.org/software/diffutils/ 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 ---- - ---- start ---- - [area]: [short line describing the main effect] + 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 - [separate the above single line from the rest with an empty line] +3.6 About pull requests - [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 ---- + With git (and especially github) it is easy and tempting to send a pull + request to the curl project to have changes merged this way instead of + mailing patches to the curl-library mailing list. - 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 + We used to dislike this but we're trying to change that and accept that this + is a frictionless way for people to contribute to the project. We now welcome + pull requests! + We will continue to avoid using github's merge tools to make the history + linear and to make sure commits follow our style guidelines. |