Contributing
Contributing means helping out.
When you contribute anything to the project—code, documentation, bug fixes,suggestions or just good advice—we assume you do this with permission and youare not breaking any contracts or laws by providing that to us. If you do nothave permission, do not contribute it to us.
Contributing to a project like curl could be many different things. Whilesource code is the stuff that is needed to build the products, we are alsodepending on good documentation, testing (both test code and testinfrastructure), web content, user support and more.
Send your changes or suggestions to the team and by working together we canfix problems, improve functionality, clarify documentation, add features ormake anything else you help out with land in the proper place. We make sureimproved code and docs get merged into the source tree properly and othersorts of contributions are suitable received.
Send your contributions on amailing list, file an issueor submit a pull request.
Suggestions
Ideas are easy, implementations are hard. Yes, we do appreciate good ideas andsuggestions of what to do and how to do it, but the chances that the ideasactually turn into real features grow substantially if you also volunteer toparticipate in converting the idea into reality.
We already gather ideas in theTODO document and we are generally aware ofthe current trends in the popular networking protocols so there is usually noneed to remind us about those.
What to add
The best approach to add anything to curl or libcurl is, of course, to firstbring the idea and suggestion to the curl project team members and thendiscuss with them if the idea is feasible for inclusion and then how animplementation is best done—and done in the best possible way to get mergedinto the source code repository, assuming that is what you want.
The project generally approves functions that improve the support for thecurrent protocols, especially features that popular clients or browsers havebut that curl still lacks.
Of course, you can also add contents to the project that are not code, likedocumentation, graphics or website contents, but the general rules applyequally to that.
If you are fixing a problem you have or a problem that others are reporting,we are thrilled to receive your fixes and merge them as soon as possible,
What not to add
There are no good rules that say what features you can or cannot add or thatwe never accept, but let me instead try to mention a few things you shouldavoid to get less friction and to be successful, faster:
Do not write up a huge patch first and then send it to the list fordiscussion. Always start out by discussing on the list, and send yourinitial review requests early to get feedback on your design andapproach. It saves you from wasting time going down a route that might needrewriting in the end anyway.
When introducing things in the code, you need to follow the style andarchitecture that already exists. When you add code to the ordinary transfercode path, it must, for example, work asynchronously in a non-blockingmanner. We do not accept new code that introduces blocking behaviors—wealready have too many of those that we have not managed to remove yet.
Quick hacks or dirty solutions that have a high risk of not working onplatforms you do not run or on architectures you do not know. We do not careif you are in a hurry or that it works for you. We do not accept high riskcode or code that is hard to read or understand.
Code that breaks the build. Sure, we accept that we sometimes have to addcode to certain areas that makes the new functionality perhaps depend on aspecific 3rd party library or a specific operating system and similar, butwe cannever do that at the expense of all other systems. We do not breakthe build, and we make sure all tests keep running successfully.
git
Our preferred source control tool isgit.
While git is sometimes not the easiest tool to learn and master, all the basicsteps a casual developer and contributor needs to know are straight-forwardand do not take much time or effort to learn.
This book does not help you learn git. All software developers in this day andage should learn git anyway.
The curl git tree can be browsed with a web browser on our GitHub page athttps://github.com/curl/curl.
To check out the curl source code from git, you can clone it like this:
git clone https://github.com/curl/curl.gitPull request
A popular and convenient way to make your own changes and contribute them backto the project is by doing a so-called pull request on GitHub.
First, you create your own version of the source tree, called a fork, on theGithub website. That way you get your own version of the curl git tree thatyou can clone to a local copy.
You edit your own local copy, commit the changes, push them to the gitrepository on Github and then on the Github website you can select to createa pull request based on your changes done to your local repository clone ofthe original curl repository.
We recommend doing your work meant for a pull request in a dedicated separatebranch and not in master, just to make it easier for you to update a pullrequest, like after review, for example, or if you realize it was a dead end andyou decide to just throw it away.
Make a patch for the mailing list
Even if you opt to not make a pull request but prefer the old fashioned andtrusted method of sending a patch to the curl-library mailing list, it isstill a good practice to work in a local git branch and commit your changesthere.
A branch makes it easy to edit and rebase when you need to change things andit makes it easy to keep syncing to the master branch when things are updatedupstream.
Once your commits are fine enough to get sent to the mailing list, you justcreate patches withgit format-patch and send them away. Even more fancyusers go directly togit send-email and have git send the email itself.
git commit style
When you commit a patch to git, you give it a commit message that describesthe change you are committing. We have a certain style in the project that weask you to use:
[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 describes as much aspossible as to why this change is made, and possibly what thingsit 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]Do not forget to usegit commit --author="Jane Doe <jane@example.com>" ifyou commit someone else's work, and make sure that you have your own Githubusername and email setup correctly in git before you commit via commandsbelow:
git config --global user.name "johndoe"git config --global user.email "johndoe@example.com"The author and the *-by: lines are, of course, there to make sure we give theproper credit in the project. We do not want to take someone else's workwithout clearly attributing where it comes from. Giving correct credit is ofutmost importance.
Who decides what goes in?
First, it might not be obvious to everyone but there is, of course, only alimited set of people that can actually merge commits into the actual officialgit repository. Let's call them the core team.
Everyone else can fork off their own curl repository to which they can commitand push changes and host them online and build their own curl versions fromand so on, but in order to get changes into theofficial repository they needto be pushed by a trusted person.
The core team is a small set of curl developers who have been around forseveral years and have shown they are skilled developers and that they fullycomprehend the values and the style of development we do in this project. Theyare some of the people listed in theThe development team section.
You can always bring a discussion to the mailing list and argue why you thinkyour changes should get accepted, or perhaps even object to other changes thatare getting in and so forth. You can even suggest yourself or someone else tobe given "push rights" and become one of the selected few in that team.
Daniel remains the project leader and while it is rarely needed, he has thefinal say in debates that do not seem to sway in either direction or fail toreach consensus.