[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