1Contributing to sabre projects
2==============================
3
4Want to contribute to sabre/dav? Here are some guidelines to ensure your patch
5gets accepted.
6
7
8Building a new feature? Contact us first
9----------------------------------------
10
11We may not want to accept every feature that comes our way. Sometimes
12features are out of scope for our projects.
13
14We don't want to waste your time, so by having a quick chat with us first,
15you may find out quickly if the feature makes sense to us, and we can give
16some tips on how to best build the feature.
17
18If we don't accept the feature, it could be for a number of reasons. For
19instance, we've rejected features in the past because we felt uncomfortable
20assuming responsibility for maintaining the feature.
21
22In those cases, it's often possible to keep the feature separate from the
23sabre projects. sabre/dav for instance has a plugin system, and there's no
24reason the feature can't live in a project you own.
25
26In that case, definitely let us know about your plugin as well, so we can
27feature it on [sabre.io][4].
28
29We are often on [IRC][5], in the #sabredav channel on freenode. If there's
30no one there, post a message on the [mailing list][6].
31
32
33Coding standards
34----------------
35
36sabre projects follow:
37
381. [PSR-1][1]
392. [PSR-4][2]
40
41sabre projects don't follow [PSR-2][3].
42
43In addition to that, here's a list of basic rules:
44
451. PHP 5.4 array syntax must be used every where. This means you use `[` and
46   `]` instead of `array(` and `)`.
472. Use PHP namespaces everywhere.
483. Use 4 spaces for indentation.
494. Try to keep your lines under 80 characters. This is not a hard rule, as
50   there are many places in the source where it felt more sensibile to not
51   do so. In particular, function declarations are never split over multiple
52   lines.
535. Opening braces (`{`) are _always_ on the same line as the `class`, `if`,
54   `function`, etc. they belong to.
556. `public` must be omitted from method declarations. It must also be omitted
56   for static properties.
577. All files should use unix-line endings (`\n`).
588. Files must omit the closing php tag (`?>`).
599. `true`, `false` and `null` are always lower-case.
6010. Constants are always upper-case.
6111. Any of the rules stated before may be broken where this is the pragmatic
62    thing to do.
63
64
65Unit test requirements
66----------------------
67
68Any new feature or change requires unittests. We use [PHPUnit][7] for all our
69tests.
70
71Adding unittests will greatly increase the likelyhood of us quickly accepting
72your pull request. If unittests are not included though for whatever reason,
73we'd still _love_ your pull request.
74
75We may have to write the tests ourselves, which can increase the time it takes
76to accept the patch, but we'd still really like your contribution!
77
78To run the testsuite jump into the directory `cd tests` and trigger `phpunit`.
79Make sure you did a `composer install` beforehand.
80
81[1]: http://www.php-fig.org/psr/psr-1/
82[2]: http://www.php-fig.org/psr/psr-4/
83[3]: http://www.php-fig.org/psr/psr-2/
84[4]: http://sabre.io/
85[5]: irc://freenode.net/#sabredav
86[6]: http://groups.google.com/group/sabredav-discuss
87[7]: http://phpunit.de/
88