[CalendarServer-changes] [4651] CalendarServer/trunk/HACKING
source_changes at macosforge.org
source_changes at macosforge.org
Wed Oct 28 11:41:03 PDT 2009
Revision: 4651
http://trac.macosforge.org/projects/calendarserver/changeset/4651
Author: wsanchez at apple.com
Date: 2009-10-28 11:41:03 -0700 (Wed, 28 Oct 2009)
Log Message:
-----------
Clean up formatting
Modified Paths:
--------------
CalendarServer/trunk/HACKING
Modified: CalendarServer/trunk/HACKING
===================================================================
--- CalendarServer/trunk/HACKING 2009-10-28 00:36:10 UTC (rev 4650)
+++ CalendarServer/trunk/HACKING 2009-10-28 18:41:03 UTC (rev 4651)
@@ -1,36 +1,34 @@
Developer's Guide to Hacking the Calendar Server
================================================
-If you are interested in contributing to Darwin Calendar Server project,
-please read this document.
+If you are interested in contributing to Darwin Calendar Server
+project, please read this document.
Participating in the Community
==============================
Although the Calendar Server is sponsored and hosted by Apple
Inc. (http://www.apple.com/), it's a true open-source project under an
-Apache license. At present, the developers work for Apple, but that's
-due to the project being new and originating at Apple. Contributions
-from other developers are welcome, and, as with all open development
-projects, may lead to "commit access" and a voice in the future of the
-project.
+Apache license. Contributions from other developers are welcome, and,
+as with all open development projects, may lead to "commit access" and
+a voice in the future of the project.
The community exists mainly through mailing lists and a Subversion
repository. To participate, go to:
- http://trac.calendarserver.org/projects/calendarserver/wiki/MailLists
+ http://trac.calendarserver.org/projects/calendarserver/wiki/MailLists
and join the appropriate mailing lists. We also use IRC, as described
here:
- http://trac.calendarserver.org/projects/calendarserver/wiki/IRC
+ http://trac.calendarserver.org/projects/calendarserver/wiki/IRC
There are many ways to join the project. One may write code, test the
software and file bugs, write documentation, etc.
The bug tracking database is here:
- http://trac.calendarserver.org/projects/calendarserver/report
+ http://trac.calendarserver.org/projects/calendarserver/report
To help manage the issues database, read over the issue summaries,
looking and testing for issues that are either invalid, or are
@@ -51,44 +49,52 @@
Check out the sources using Subversion from this repository URL:
- http://svn.macosforge.org/repository/calendarserver/CalendarServer/trunk/
+ http://svn.macosforge.org/repository/calendarserver/CalendarServer/trunk/
It is assumed here that you are familiar with and able to use
Subversion. More information about Subversion, including
documentation and download instructions, is available from:
- http://subversion.tigris.org/
+ http://subversion.tigris.org/
Directory Layout
================
A rough guide to the source tree:
- * doc/ - User and developer documentation, including relevant
+ * ``doc/`` - User and developer documentation, including relevant
protocol specifications and extensions.
- * bin/ - Executable programs.
+ * ``bin/`` - Executable programs.
- * conf/ - Configuration files.
+ * ``conf/`` - Configuration files.
- * contrib/ - Stuff that works with the Calendar Server, but that the
- Calendar Server does not depend on.
+ * ``calendarserver/`` - Source code for the Calendar Server
- * support/ - Support files of possible use to developers.
+ * ``twistedcaldav/`` - Source code for CalDAV library
- * twistedcaldav/ - Source code for the Calendar Server.
+ * ``twistedcaldav/`` - Source code for extensions to Twisted
- * lib-patches/ - Patch files which modify 3rd-party software required
- by the Calendar Server. In an ideal world, this would be empty.
+ * ``lib-patches/`` - Patch files which modify 3rd-party software
+ required by the Calendar Server. In an ideal world, this would be
+ empty.
- * twisted/ - Files required to set up the Calendar Server as a
+ * ``twisted/`` - Files required to set up the Calendar Server as a
Twisted service. Twisted (http://twistedmatrix.com/) is a
networking framework upon which the Calendar Server is built.
+ * ``locales/`` - Localization files.
+
+ * ``contrib/`` - Extra stuff that works with the Calendar Server, or
+ that helps integrate with other software (including operating
+ systems), but that the Calendar Server does not depend on.
+
+ * ``support/`` - Support files of possible use to developers.
+
Coding Standards
================
-The vast majority of the Calendar Server is writen in the Python
+The vast majority of the Calendar Server is written in the Python
programming language. When writing Python code for the Calendar
Server, please observe the following conventions.
@@ -98,18 +104,18 @@
comply with these standards are welcome, and code chanegs that do not
conform to these standards are discouraged.
-We require Python 2.5 or higher. It is OK to write code that does not
-work with Python versions older than 2.5. At present, adding code
-that requires the in-development Python 2.6/3.0 or newer is not allowed.
+**We require Python 2.5 or higher.** It therefore is OK to write code
+that does not work with Python versions older than 2.5. At present,
+adding code that requires Python 2.6/3.0 or later is not allowed.
Read PEP-8:
- http://www.python.org/dev/peps/pep-0008/
+ http://www.python.org/dev/peps/pep-0008/
For the most part, our code should follow PEP-8, with a few exceptions
and a few additions. It is also useful to review the Twisted Coding
-Standard, from which we borrow some standards, though we do't follow
-it per se:
+Standard, from which we borrow some standards, though we don't
+strictly follow it:
http://twistedmatrix.com/trac/browser/trunk/doc/development/policy/coding-standard.xhtml?format=raw
@@ -127,14 +133,18 @@
* PEP-8 recommends using a backslash to break long lines up:
+ ::
+
if width == 0 and height == 0 and \
- color == 'red' and emphasis == 'strong' or \
- highlight > 100:
- raise ValueError("sorry, you lose")
+ color == 'red' and emphasis == 'strong' or \
+ highlight > 100:
+ raise ValueError("sorry, you lose")
Don't do that, it's gross, and the indentation for the "raise" line
gets confusing. Use parentheses:
+ ::
+
if (
width == 0 and
height == 0 and
@@ -146,6 +156,8 @@
Just don't do it the way PEP-8 suggests:
+ ::
+
if width == 0 and height == 0 and (color == 'red' or
emphasis is None):
raise ValueError("I don't think so")
@@ -154,6 +166,8 @@
* Lining up assignments is OK, within reason:
+ ::
+
cars = 4
motorbikes = 8
bicycles = 18
@@ -163,6 +177,8 @@
* Close parentheses and brackets such as '()', '[]' and '{}' at the
same indent level as the line in which you opened it:
+ ::
+
launchAtTarget(
target="David",
object=PaperWad(
@@ -175,6 +191,8 @@
* Long lines are often due to long strings. Try to break strings up
into multiple lines:
+ ::
+
processString(
"This is a very long string with a lot of text. "
"Fortunately, it is easy to break it up into parts "
@@ -187,6 +205,8 @@
* It's OK to break generator expressions and list comprehensions into
multiple lines. For example:
+ ::
+
myStuff = (
item.obtainUsefulValue()
for item in someDataStore
@@ -197,12 +217,16 @@
importing modules and referencing the symbol via the module unless
it doesn't make sense to do so. For example:
+ ::
+
from subprocess import Popen
process = Popen(...)
Instead of:
+ ::
+
import subprocess
process = subprocess.Popen(...)
@@ -222,6 +246,8 @@
* A deferred that will be immediately returned may be called "d":
+ ::
+
d = doThisAndThat()
d.addCallback(onResult)
d.addErrback(onError)
@@ -230,6 +256,8 @@
* When using waitForDeferred() in a deferredGenerator, "x" may be
used to clear the deferred if the deferred result will be ignored.
+ ::
+
x = waitForDeferred(doThisAndThat())
yield x
x.getResult()
@@ -237,6 +265,8 @@
* "_" may be used to denote unused arguments in callbacks:
+ ::
+
def onCompletion(_):
# Don't care about result of doThisAndThat() in here;
# we only care that it has completed.
@@ -251,9 +281,9 @@
"_", but a locally scoped variable should not, as there is no
danger of it being exposed.
- * Per twisted convention, use camel-case (fuzzyWidget, doThisAndThat())
- for symbol names instead of using underbars (fuzzy_widget,
- do_this_and_that()).
+ * Per twisted convention, use camel-case (fuzzyWidget,
+ doThisAndThat()) for symbol names instead of using underbars
+ (fuzzy_widget, do_this_and_that()).
Use of underbars is reserved for implied dispatching and the like
(eg. http_FOO()). See the Twisted Coding Standard for details.
@@ -261,10 +291,14 @@
* Always use a tuple when using % formatting, even when only one
value is being provided:
+ ::
+
error = "Unexpected value: %s" % (value,)
Do not use the non-tuple form:
+ ::
+
error = "Unexpected value: %s" % value
Which is allowed in Python, but results in an programming error if
@@ -272,12 +306,16 @@
* Don't use a trailing ',' at the end of a tuple if it's on one line:
+ ::
+
numbers = (1,2,3,) # No
numbers = (1,2,3) # Yes
It's desirable on multiple lines, though, as that makes re-ordering
items easy, and avoids a diff on the last line when adding another:
+ ::
+
strings = (
"This is a string.",
"And so is this one.",
@@ -299,6 +337,8 @@
* Begin all multi-line docstrings with a 3 double quotes and a
newline:
+ ::
+
def doThisAndThat(...):
"""
Do this, and that.
@@ -327,8 +367,10 @@
it.
The most reliable way to ensure that a stream is closed is to put
- the call to `close()` in a `finally` block:
+ the call to ``close()`` in a ``finally`` block:
+ ::
+
stream = file(somePath)
try:
... do something with stream ...
@@ -353,6 +395,8 @@
tests. You can run specific tests by specifying them as arguments
like this:
+ ::
+
./test twistedcaldav.static
All non-trivial public callables must have unit tests. (Note we don't
@@ -363,8 +407,8 @@
module names should start with `test_`. Twisted has some tips on
writing tests here:
- http://twistedmatrix.com/projects/core/documentation/howto/testing.html
- http://twistedmatrix.com/trac/browser/trunk/doc/development/policy/test-standard.xhtml?format=raw
+ http://twistedmatrix.com/projects/core/documentation/howto/testing.html
+ http://twistedmatrix.com/trac/browser/trunk/doc/development/policy/test-standard.xhtml?format=raw
We also use CalDAVTester (which is a companion to Calendar Server in
the same Mac OS Forge project), which performs more "black box"-type
@@ -373,7 +417,7 @@
and then running CalDAVTester against it. For information about
CalDAVTester is available here:
- http://trac.calendarserver.org/projects/calendarserver/wiki/CalDAVTester
+ http://trac.calendarserver.org/projects/calendarserver/wiki/CalDAVTester
Commit Policy
=============
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20091028/cacea1ee/attachment-0001.html>
More information about the calendarserver-changes
mailing list