diff options
| -rw-r--r-- | docs/CONTRIBUTE | 146 |
1 files changed, 78 insertions, 68 deletions
diff --git a/docs/CONTRIBUTE b/docs/CONTRIBUTE index 9e84175ba..e6a85a514 100644 --- a/docs/CONTRIBUTE +++ b/docs/CONTRIBUTE @@ -23,13 +23,14 @@ 2.5 Document 2.6 Test Cases - 3. Pushing Out Your Changes - 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. Sharing Your Changes + 3.1 How to get your changes into the main sources + 3.2 About pull requests + 3.3 Making quality patches 3.5 Write good commit messages - 3.6 About pull requests + 3.6 Write Access to git Repository + 3.7 How To Make a Patch with git + 3.8 How To Make a Patch without git ============================================================================== @@ -88,7 +89,9 @@ When writing C code, follow the CODE_STYLE already established in the project. Consistent style makes code easier to read and mistakes less likely - to happen. + to happen. Run 'make checksrc' before you submit anything, to make sure you + follow the basic style. That script doesn't verify everything, but if it + complains you know you have work to do. 2.2 Non-clobbering All Over @@ -144,17 +147,76 @@ hard to write tests for, do explain exactly how you have otherwise tested and verified your changes. -3. Pushing Out Your Changes +3. Sharing Your Changes -3.1 Write Access to git Repository +3.1 How to get your changes into the main sources - If you are a frequent contributor, or have another good reason, you can of - 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. + Ideally you file a pull request on github, but you can also send your plain + patch to the curl-library mailing list. -3.2 How To Make a Patch with git + Either way, your change will be reviewed and discussed there and you will be + expected to correct flaws pointed out and update accordingly, or the change + risk stalling and eventually just get deleted without action. As a submitter + of a change, you are the owner of that change until it has been merged. + + Respond on the list or on github about the change and answer questions and/or + fix nits/flaws. This is very important. We will take lack of replies as a + sign that you're not very anxious to get your patch accepted and we tend to + simply drop such changes. + +3.2 About pull requests + + With github it is easy 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. See https://github.com/curl/curl/pulls + + We prefer pull requests as it makes it a proper git commit that is easy to + merge and they are easy to track and not that easy to loose in a flood of + many emails, like they sometimes do on the mailing lists. + + When you ajust your pull requests after review, consider squashing the + commits so that we can review the full updated version more easily. + +3.3 Making quality patches + + Make the patch against as recent sources as possible. + + If you've followed the tips in this document and your patch still hasn't been + incorporated or responded to after some weeks, consider resubmitting it to + the list or better yet: change it to a pull request. + +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 Write Access to git Repository + + If you are a very frequent contributor, you may be given push access to the + git repository and then you'll be able to push your changes straight into the + git repo instead of sending changes as pull requests or by mail as patches. + + Just ask if this is what you'd want. You will be required to have posted + several high quality patches first, before you can be granted push access. + +3.7 How To Make a Patch with git You need to first checkout the repository: @@ -180,7 +242,7 @@ 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 +3.8 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 @@ -207,55 +269,3 @@ 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 About pull requests - - 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. - - 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. |