First off - you rock! Community contributions are so awesome and have resulted in some awesome features landing in Sag.
This guide is meant to make it as easy as possible to contribute your code to Sag.
-
Fork the Sag project. If you have a GitHub account this is very easy: just hit "fork" on the Sag page and you will get your own repo. http://help.github.com/fork-a-repo/
-
Every feature or bug fix should be in its own branch. Ideally the branch name will be related to what you're contributing (iss-32, newFeatureName, etc.).
-
Make your commits to the branch atomic so that there is a clearly defined commit for each change you make. For example, if you're writing a function in Sag.php that relies on new functionality in SagHTTPAdapter.php, make one commit for the SagHTTPAdapter.php work and then commit your work in Sag.php. This is just git best practices.
-
Write tests! One of the reasons Sag is so popular and good is that we use an automated testing framework to prevent regressions, check for compatibility against new versions of CouchDB, etc. Your contribution will not be accepted without supporting tests.
-
Your code is not complete until you run
make check
in Sag's root directory. Your code will not land in Sag if it breaks tests. -
Once your work is done issue a pull request to the Sag project. http://help.github.com/send-pull-requests/
It is good form to follow a project's coding style when contributing. Do not take it upon yourself to rewrite every comment, drop in or delete white spaces all over the place, etc.
-
No hard tabs. Please set your editor to use 2 space soft tabs.
-
There is never any reason to use globals or goto statements.
-
Don't use single letter variable names. The exception to this rule is if you are iterating over an array or object and use
$i
. -
Use camel case, not underscores. That's why we have
usingSSL()
instead ofusing_ssl()
. -
Put curly braces on the same line as the function definition, loop statement, etc.
Example:
function sillyArraySearch($arr, $val) {
foreach($arr as $k => $v) {
if($v == $val) {
return true;
}
}
}
- We use phpdocs to generate documentation. Therefore every function should have a properly formatted comment block with parameter and return information.
Example comment for the above sillyArraySearch function:
/**
* This is a naive example of how to search an array for a given value.
*
* @param array $arr The array to search.
* @param mixed $val The value that we are searching for.
* @return bool Returns true if the array contains the value, else false.
*/
- When considering multiple values for a single variable use a switch instead of multiple if/else-if blocks. This makes it crystal clear that all of your logic centers around the value of one variable.
What not to do:
if($foo == 'bwah') {
//...
}
elseif($foo == 1) {
//...
}
else {
throw SagException('Unexpected value for $foo.');
}
What you should do:
switch($foo) {
case 'bwah':
//...
break;
case 1:
//...
break;
default:
throw SagException('Unexpected value for $foo.');
}
Worry not, Sag does not support PHP's strict mode.
In point #4, you might mention an easy test they can "cheat off of"
like, "But don't worry, it's easy…see!" (where "see!" is a link to the simple test) or some such...
Also, what's your preference for long variable names? $long_variable_name?