[CalendarServer-changes] [12425] CalendarServer/trunk
source_changes at macosforge.org
source_changes at macosforge.org
Wed Mar 12 11:23:13 PDT 2014
Revision: 12425
http://trac.calendarserver.org//changeset/12425
Author: wsanchez at apple.com
Date: 2014-01-22 17:15:50 -0800 (Wed, 22 Jan 2014)
Log Message:
-----------
Yay file extentions.
Added Paths:
-----------
CalendarServer/trunk/HACKING.rst
CalendarServer/trunk/LICENSE.txt
CalendarServer/trunk/README.rst
Removed Paths:
-------------
CalendarServer/trunk/HACKING
CalendarServer/trunk/LICENSE
CalendarServer/trunk/README
Deleted: CalendarServer/trunk/HACKING
===================================================================
--- CalendarServer/trunk/HACKING 2014-01-23 01:15:05 UTC (rev 12424)
+++ CalendarServer/trunk/HACKING 2014-01-23 01:15:50 UTC (rev 12425)
@@ -1,459 +0,0 @@
-Developer's Guide to Hacking the Calendar Server
-================================================
-
-If you are interested in contributing to the Calendar and Contacts
-Server project, please read this document.
-
-
-Participating in the Community
-==============================
-
-Although the Calendar and Contacts Server is sponsored and hosted by
-Apple Inc. (http://www.apple.com/), it's a true open-source project
-under an 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
-
-and join the appropriate mailing lists. We also use IRC, as described
-here:
-
- 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
-
-To help manage the issues database, read over the issue summaries,
-looking and testing for issues that are either invalid, or are
-duplicates of other issues. Both kinds are very common, the first
-because bugs often get unknowingly fixed as side effects of other
-changes in the code, and the second because people sometimes file an
-issue without noticing that it has already been reported. If you are
-not sure about an issue, post a question to
-calendarserver-dev at lists.macosforge.org.
-
-Before filing bugs, please take a moment to perform a quick search to
-see if someone else has already filed your bug. In that case, add a
-comment to the existing bug if appropriate and monitor it, rather than
-filing a duplicate.
-
-
-Obtaining the Code
-==================
-
-The source code to the Calendar and Contacts Server is available via
-Subversion at this repository URL:
-
- http://svn.calendarserver.org/repository/calendarserver/CalendarServer/trunk/
-
-You can also browse the repository directly using your web browser, or
-use WebDAV clients to browse the repository, such as Mac OS X's Finder
-(`Go -> Connect to Server`).
-
-A richer web interface which provides access to version history and
-logs is available via Trac here:
-
- http://trac.calendarserver.org/browser/
-
-Most developers will want to use a full-featured Subversion client.
-More information about Subversion, including documentation and client
-download instructions, is available from the Subversion project:
-
- http://subversion.tigris.org/
-
-
-Directory Layout
-================
-
-A rough guide to the source tree:
-
- * ``doc/`` - User and developer documentation, including relevant
- protocol specifications and extensions.
-
- * ``bin/`` - Executable programs.
-
- * ``conf/`` - Configuration files.
-
- * ``calendarserver/`` - Source code for the Calendar and Contacts
- Server
-
- * ``twistedcaldav/`` - Source code for CalDAV library
-
- * ``twistedcaldav/`` - Source code for extensions to Twisted
-
- * ``lib-patches/`` - Patch files which modify 3rd-party software
- required by the Calendar and Contacts Server. In an ideal world,
- this would be empty.
-
- * ``twisted/`` - Files required to set up the Calendar and Contacts
- Server as a Twisted service. Twisted (http://twistedmatrix.com/)
- is a networking framework upon which the Calendar and Contacts
- Server is built.
-
- * ``locales/`` - Localization files.
-
- * ``contrib/`` - Extra stuff that works with the Calendar and
- Contacts Server, or that helps integrate with other software
- (including operating systems), but that the Calendar and Contacts
- Server does not depend on.
-
- * ``support/`` - Support files of possible use to developers.
-
-
-Coding Standards
-================
-
-The vast majority of the Calendar and Contacts Server is written in
-the Python programming language. When writing Python code for the
-Calendar and Contacts Server, please observe the following
-conventions.
-
-Please note that all of our code at present does not follow these
-standards, but that does not mean that one shouldn't bother to do so.
-On the contrary, code changes that do nothing but reformat code to
-comply with these standards are welcome, and code changes that do not
-conform to these standards are discouraged.
-
-**We require Python 2.6 or higher.** It therefore is OK to write code
-that does not work with Python versions older than 2.6.
-
-Read PEP-8:
-
- 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 don't
-strictly follow it:
-
- http://twistedmatrix.com/trac/browser/trunk/doc/development/policy/coding-standard.xhtml?format=raw
-
-Key items to follow, and specifics:
-
- * Indent level is 4 spaces.
-
- * Never indent code with tabs. Always use spaces.
-
-PEP-8 items we do not follow:
-
- * 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")
-
- 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
- color == "red" and
- emphasis == "strong" or
- highlight > 100
- ):
- raise ValueError("sorry, you lose")
-
- 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")
-
- Because that's just silly.
-
-Additions:
-
- * 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(
- message="Yo!",
- crumpleFactor=0.7,
- ),
- speed=0.4,
- )
-
- * 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 "
- "like this."
- )
-
- Similarly, callables that take many arguments can be broken up into
- multiple lines, as in the ``launchAtTarget()`` example above.
-
- * Breaking generator expressions and list comprehensions into
- multiple lines can improve readability. For example:
-
- ::
-
- myStuff = (
- item.obtainUsefulValue()
- for item in someDataStore
- if item.owner() == me
- )
-
- * Import symbols (especially class names) from modules instead of
- 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(...)
-
- This makes code shorter and makes it easier to replace one implementation
- with another.
-
- * All files should have an ``__all__`` specification. Put them at the
- top of the file, before imports (PEP-8 puts them at the top, but
- after the imports), so you can see what the public symbols are for
- a file right at the top.
-
- * It is more important that symbol names are meaningful than it is
- that they be concise. ``x`` is rarely an appropriate name for a
- variable. Avoid contractions: ``transmogrifierStatus`` is more useful
- to the reader than ``trmgStat``.
-
- * A deferred that will be immediately returned may be called ``d``:
-
- ::
-
- d = doThisAndThat()
- d.addCallback(onResult)
- d.addErrback(onError)
- return d
-
- * Do not use ``deferredGenerator``. Use ``inlineCallbacks`` instead.
-
- * That said, avoid using ``inlineCallbacks`` when chaining deferreds
- is straightforward, as they are more expensive. Use
- ``inlineCallbacks`` when necessary for keeping code maintainable,
- such as when creating serialized deferreds in a for loop.
-
- * ``_`` may be used to denote unused callback arguments:
-
- ::
-
- def onCompletion(_):
- # Don't care about result of doThisAndThat() in here;
- # we only care that it has completed.
- doNextThing()
-
- d = doThisAndThat()
- d.addCallback(onCompletion)
- return d
-
- * Do not prefix symbols with ``_`` unless they might otherwise be
- exposed as a public symbol: a private method name should begin with
- ``_``, but a locally scoped variable should not, as there is no
- danger of it being exposed. Locally scoped variables are already
- private.
-
- * Per twisted convention, use camel-case (``fuzzyWidget``,
- ``doThisAndThat()``) for symbol names instead of using underscores
- (``fuzzy_widget``, ``do_this_and_that()``).
-
- Use of underscores is reserved for implied dispatching and the like
- (eg. ``http_FOO()``). See the Twisted Coding Standard for details.
-
- * Do not use ``%``-formatting:
-
- ::
-
- error = "Unexpected value: %s" % (value,)
-
- Use PEP-3101 formatting instead:
-
- ::
-
- error = "Unexpected value: {value}".format(value=value)
-
- * If you must use ``%``-formatting for some reason, always use a tuple as
- the format argument, even when only one value is being provided:
-
- ::
-
- error = "Unexpected value: %s" % (value,)
-
- Never use the non-tuple form:
-
- ::
-
- error = "Unexpected value: %s" % value
-
- Which is allowed in Python, but results in a programming error if
- ``type(value) is tuple and len(value) != 1``.
-
- * 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
-
- The trailing comma is 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.",
- "And here is yet another string.",
- )
-
- * Docstrings are important. All public symbols (anything declared in
- ``__all__``) must have a correct docstring. The script
- ``docs/Developer/gendocs`` will generate the API documentation using
- ``pydoctor``. See the ``pydoctor`` documentation for details on the
- formatting:
-
- http://codespeak.net/~mwh/pydoctor/
-
- Note: existing docstrings need a complete review.
-
- * Use PEP-257 as a guideline for docstrings.
-
- * Begin all multi-line docstrings with 3 double quotes and a
- newline:
-
- ::
-
- def doThisAndThat(...):
- """
- Do this, and that.
- ...
- """
-
-
-Best Practices
-==============
-
- * If a callable is going to return a Deferred some of the time, it
- should return a deferred all of the time. Return ``succeed(value)``
- instead of ``value`` if necessary. This avoids forcing the caller
- to check as to whether the value is a deferred or not (eg. by using
- ``maybeDeferred()``), which is both annoying to code and potentially
- expensive at runtime.
-
- * Be proactive about closing files and file-like objects.
-
- For a lot of Python software, letting Python close the stream for
- you works fine, but in a long-lived server that's processing many
- data streams at a time, it is important to close them as soon as
- possible.
-
- On some platforms (eg. Windows), deleting a file will fail if the
- file is still open. By leaving it up to Python to decide when to
- close a file, you may find yourself being unable to reliably delete
- it.
-
- The most reliable way to ensure that a stream is closed is to put
- the call to ``close()`` in a ``finally`` block:
-
- ::
-
- stream = file(somePath)
- try:
- ... do something with stream ...
- finally:
- stream.close()
-
-
-Testing
-=======
-
-Be sure that all of the units tests pass before you commit new code.
-Code that breaks units tests may be reverted without further
-discussion; it is up to the committer to fix the problem and try
-again.
-
-Note that repeatedly committing code that breaks units tests presents
-a possible time sink for other developers, and is not looked upon
-favorably.
-
-Units tests can be run rather easily by executing the ``test`` script
-at the top of the Calendar and Contacts Server source tree. By
-default, it will run all of the Calendar and Contacts Server tests
-followed by all of the Twisted 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
-don't totally comply with this rule; that's a problem we'd like to
-fix.) All other callables should have unit tests.
-
-Units tests are written using the ``twisted.trial`` framework. Test
-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
-
-We also use CalDAVTester (which is a companion to the Calendar and
-Contacts Server in the same Mac OS Forge project), which performs more
-"black box"-type testing against the server to ensure compliance with
-the CalDAV protocol. That requires running the server with a test
-configuration and then running CalDAVTester against it. For
-information about CalDAVTester is available here:
-
- http://trac.calendarserver.org/projects/calendarserver/wiki/CalDAVTester
-
-
-Commit Policy
-=============
-
-We follow a commit-then-review policy for relatively "safe" changes to
-the code. If you have a rather straightforward change or are working
-on new functionality that does not affect existing functionality, you
-can commit that code without review at your discretion.
-
-Developers are encouraged to monitor the commit notifications that are
-sent via email after each commit and review/critique/comment on
-modifications as appropriate.
-
-Any changes that impact existing functionality should be reviewed by
-another developer before being committed. Large changes should be
-made on a branch and merged after review.
-
-This policy relies on the discretion of committers.
Copied: CalendarServer/trunk/HACKING.rst (from rev 12409, CalendarServer/trunk/HACKING)
===================================================================
--- CalendarServer/trunk/HACKING.rst (rev 0)
+++ CalendarServer/trunk/HACKING.rst 2014-01-23 01:15:50 UTC (rev 12425)
@@ -0,0 +1,459 @@
+Developer's Guide to Hacking the Calendar Server
+================================================
+
+If you are interested in contributing to the Calendar and Contacts
+Server project, please read this document.
+
+
+Participating in the Community
+==============================
+
+Although the Calendar and Contacts Server is sponsored and hosted by
+Apple Inc. (http://www.apple.com/), it's a true open-source project
+under an 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
+
+and join the appropriate mailing lists. We also use IRC, as described
+here:
+
+ 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
+
+To help manage the issues database, read over the issue summaries,
+looking and testing for issues that are either invalid, or are
+duplicates of other issues. Both kinds are very common, the first
+because bugs often get unknowingly fixed as side effects of other
+changes in the code, and the second because people sometimes file an
+issue without noticing that it has already been reported. If you are
+not sure about an issue, post a question to
+calendarserver-dev at lists.macosforge.org.
+
+Before filing bugs, please take a moment to perform a quick search to
+see if someone else has already filed your bug. In that case, add a
+comment to the existing bug if appropriate and monitor it, rather than
+filing a duplicate.
+
+
+Obtaining the Code
+==================
+
+The source code to the Calendar and Contacts Server is available via
+Subversion at this repository URL:
+
+ http://svn.calendarserver.org/repository/calendarserver/CalendarServer/trunk/
+
+You can also browse the repository directly using your web browser, or
+use WebDAV clients to browse the repository, such as Mac OS X's Finder
+(`Go -> Connect to Server`).
+
+A richer web interface which provides access to version history and
+logs is available via Trac here:
+
+ http://trac.calendarserver.org/browser/
+
+Most developers will want to use a full-featured Subversion client.
+More information about Subversion, including documentation and client
+download instructions, is available from the Subversion project:
+
+ http://subversion.tigris.org/
+
+
+Directory Layout
+================
+
+A rough guide to the source tree:
+
+ * ``doc/`` - User and developer documentation, including relevant
+ protocol specifications and extensions.
+
+ * ``bin/`` - Executable programs.
+
+ * ``conf/`` - Configuration files.
+
+ * ``calendarserver/`` - Source code for the Calendar and Contacts
+ Server
+
+ * ``twistedcaldav/`` - Source code for CalDAV library
+
+ * ``twistedcaldav/`` - Source code for extensions to Twisted
+
+ * ``lib-patches/`` - Patch files which modify 3rd-party software
+ required by the Calendar and Contacts Server. In an ideal world,
+ this would be empty.
+
+ * ``twisted/`` - Files required to set up the Calendar and Contacts
+ Server as a Twisted service. Twisted (http://twistedmatrix.com/)
+ is a networking framework upon which the Calendar and Contacts
+ Server is built.
+
+ * ``locales/`` - Localization files.
+
+ * ``contrib/`` - Extra stuff that works with the Calendar and
+ Contacts Server, or that helps integrate with other software
+ (including operating systems), but that the Calendar and Contacts
+ Server does not depend on.
+
+ * ``support/`` - Support files of possible use to developers.
+
+
+Coding Standards
+================
+
+The vast majority of the Calendar and Contacts Server is written in
+the Python programming language. When writing Python code for the
+Calendar and Contacts Server, please observe the following
+conventions.
+
+Please note that all of our code at present does not follow these
+standards, but that does not mean that one shouldn't bother to do so.
+On the contrary, code changes that do nothing but reformat code to
+comply with these standards are welcome, and code changes that do not
+conform to these standards are discouraged.
+
+**We require Python 2.6 or higher.** It therefore is OK to write code
+that does not work with Python versions older than 2.6.
+
+Read PEP-8:
+
+ 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 don't
+strictly follow it:
+
+ http://twistedmatrix.com/trac/browser/trunk/doc/development/policy/coding-standard.xhtml?format=raw
+
+Key items to follow, and specifics:
+
+ * Indent level is 4 spaces.
+
+ * Never indent code with tabs. Always use spaces.
+
+PEP-8 items we do not follow:
+
+ * 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")
+
+ 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
+ color == "red" and
+ emphasis == "strong" or
+ highlight > 100
+ ):
+ raise ValueError("sorry, you lose")
+
+ 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")
+
+ Because that's just silly.
+
+Additions:
+
+ * 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(
+ message="Yo!",
+ crumpleFactor=0.7,
+ ),
+ speed=0.4,
+ )
+
+ * 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 "
+ "like this."
+ )
+
+ Similarly, callables that take many arguments can be broken up into
+ multiple lines, as in the ``launchAtTarget()`` example above.
+
+ * Breaking generator expressions and list comprehensions into
+ multiple lines can improve readability. For example:
+
+ ::
+
+ myStuff = (
+ item.obtainUsefulValue()
+ for item in someDataStore
+ if item.owner() == me
+ )
+
+ * Import symbols (especially class names) from modules instead of
+ 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(...)
+
+ This makes code shorter and makes it easier to replace one implementation
+ with another.
+
+ * All files should have an ``__all__`` specification. Put them at the
+ top of the file, before imports (PEP-8 puts them at the top, but
+ after the imports), so you can see what the public symbols are for
+ a file right at the top.
+
+ * It is more important that symbol names are meaningful than it is
+ that they be concise. ``x`` is rarely an appropriate name for a
+ variable. Avoid contractions: ``transmogrifierStatus`` is more useful
+ to the reader than ``trmgStat``.
+
+ * A deferred that will be immediately returned may be called ``d``:
+
+ ::
+
+ d = doThisAndThat()
+ d.addCallback(onResult)
+ d.addErrback(onError)
+ return d
+
+ * Do not use ``deferredGenerator``. Use ``inlineCallbacks`` instead.
+
+ * That said, avoid using ``inlineCallbacks`` when chaining deferreds
+ is straightforward, as they are more expensive. Use
+ ``inlineCallbacks`` when necessary for keeping code maintainable,
+ such as when creating serialized deferreds in a for loop.
+
+ * ``_`` may be used to denote unused callback arguments:
+
+ ::
+
+ def onCompletion(_):
+ # Don't care about result of doThisAndThat() in here;
+ # we only care that it has completed.
+ doNextThing()
+
+ d = doThisAndThat()
+ d.addCallback(onCompletion)
+ return d
+
+ * Do not prefix symbols with ``_`` unless they might otherwise be
+ exposed as a public symbol: a private method name should begin with
+ ``_``, but a locally scoped variable should not, as there is no
+ danger of it being exposed. Locally scoped variables are already
+ private.
+
+ * Per twisted convention, use camel-case (``fuzzyWidget``,
+ ``doThisAndThat()``) for symbol names instead of using underscores
+ (``fuzzy_widget``, ``do_this_and_that()``).
+
+ Use of underscores is reserved for implied dispatching and the like
+ (eg. ``http_FOO()``). See the Twisted Coding Standard for details.
+
+ * Do not use ``%``-formatting:
+
+ ::
+
+ error = "Unexpected value: %s" % (value,)
+
+ Use PEP-3101 formatting instead:
+
+ ::
+
+ error = "Unexpected value: {value}".format(value=value)
+
+ * If you must use ``%``-formatting for some reason, always use a tuple as
+ the format argument, even when only one value is being provided:
+
+ ::
+
+ error = "Unexpected value: %s" % (value,)
+
+ Never use the non-tuple form:
+
+ ::
+
+ error = "Unexpected value: %s" % value
+
+ Which is allowed in Python, but results in a programming error if
+ ``type(value) is tuple and len(value) != 1``.
+
+ * 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
+
+ The trailing comma is 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.",
+ "And here is yet another string.",
+ )
+
+ * Docstrings are important. All public symbols (anything declared in
+ ``__all__``) must have a correct docstring. The script
+ ``docs/Developer/gendocs`` will generate the API documentation using
+ ``pydoctor``. See the ``pydoctor`` documentation for details on the
+ formatting:
+
+ http://codespeak.net/~mwh/pydoctor/
+
+ Note: existing docstrings need a complete review.
+
+ * Use PEP-257 as a guideline for docstrings.
+
+ * Begin all multi-line docstrings with 3 double quotes and a
+ newline:
+
+ ::
+
+ def doThisAndThat(...):
+ """
+ Do this, and that.
+ ...
+ """
+
+
+Best Practices
+==============
+
+ * If a callable is going to return a Deferred some of the time, it
+ should return a deferred all of the time. Return ``succeed(value)``
+ instead of ``value`` if necessary. This avoids forcing the caller
+ to check as to whether the value is a deferred or not (eg. by using
+ ``maybeDeferred()``), which is both annoying to code and potentially
+ expensive at runtime.
+
+ * Be proactive about closing files and file-like objects.
+
+ For a lot of Python software, letting Python close the stream for
+ you works fine, but in a long-lived server that's processing many
+ data streams at a time, it is important to close them as soon as
+ possible.
+
+ On some platforms (eg. Windows), deleting a file will fail if the
+ file is still open. By leaving it up to Python to decide when to
+ close a file, you may find yourself being unable to reliably delete
+ it.
+
+ The most reliable way to ensure that a stream is closed is to put
+ the call to ``close()`` in a ``finally`` block:
+
+ ::
+
+ stream = file(somePath)
+ try:
+ ... do something with stream ...
+ finally:
+ stream.close()
+
+
+Testing
+=======
+
+Be sure that all of the units tests pass before you commit new code.
+Code that breaks units tests may be reverted without further
+discussion; it is up to the committer to fix the problem and try
+again.
+
+Note that repeatedly committing code that breaks units tests presents
+a possible time sink for other developers, and is not looked upon
+favorably.
+
+Units tests can be run rather easily by executing the ``test`` script
+at the top of the Calendar and Contacts Server source tree. By
+default, it will run all of the Calendar and Contacts Server tests
+followed by all of the Twisted 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
+don't totally comply with this rule; that's a problem we'd like to
+fix.) All other callables should have unit tests.
+
+Units tests are written using the ``twisted.trial`` framework. Test
+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
+
+We also use CalDAVTester (which is a companion to the Calendar and
+Contacts Server in the same Mac OS Forge project), which performs more
+"black box"-type testing against the server to ensure compliance with
+the CalDAV protocol. That requires running the server with a test
+configuration and then running CalDAVTester against it. For
+information about CalDAVTester is available here:
+
+ http://trac.calendarserver.org/projects/calendarserver/wiki/CalDAVTester
+
+
+Commit Policy
+=============
+
+We follow a commit-then-review policy for relatively "safe" changes to
+the code. If you have a rather straightforward change or are working
+on new functionality that does not affect existing functionality, you
+can commit that code without review at your discretion.
+
+Developers are encouraged to monitor the commit notifications that are
+sent via email after each commit and review/critique/comment on
+modifications as appropriate.
+
+Any changes that impact existing functionality should be reviewed by
+another developer before being committed. Large changes should be
+made on a branch and merged after review.
+
+This policy relies on the discretion of committers.
Deleted: CalendarServer/trunk/LICENSE
===================================================================
--- CalendarServer/trunk/LICENSE 2014-01-23 01:15:05 UTC (rev 12424)
+++ CalendarServer/trunk/LICENSE 2014-01-23 01:15:50 UTC (rev 12425)
@@ -1,202 +0,0 @@
-
- Apache License
- Version 2.0, January 2004
- http://www.apache.org/licenses/
-
- TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
- 1. Definitions.
-
- "License" shall mean the terms and conditions for use, reproduction,
- and distribution as defined by Sections 1 through 9 of this document.
-
- "Licensor" shall mean the copyright owner or entity authorized by
- the copyright owner that is granting the License.
-
- "Legal Entity" shall mean the union of the acting entity and all
- other entities that control, are controlled by, or are under common
- control with that entity. For the purposes of this definition,
- "control" means (i) the power, direct or indirect, to cause the
- direction or management of such entity, whether by contract or
- otherwise, or (ii) ownership of fifty percent (50%) or more of the
- outstanding shares, or (iii) beneficial ownership of such entity.
-
- "You" (or "Your") shall mean an individual or Legal Entity
- exercising permissions granted by this License.
-
- "Source" form shall mean the preferred form for making modifications,
- including but not limited to software source code, documentation
- source, and configuration files.
-
- "Object" form shall mean any form resulting from mechanical
- transformation or translation of a Source form, including but
- not limited to compiled object code, generated documentation,
- and conversions to other media types.
-
- "Work" shall mean the work of authorship, whether in Source or
- Object form, made available under the License, as indicated by a
- copyright notice that is included in or attached to the work
- (an example is provided in the Appendix below).
-
- "Derivative Works" shall mean any work, whether in Source or Object
- form, that is based on (or derived from) the Work and for which the
- editorial revisions, annotations, elaborations, or other modifications
- represent, as a whole, an original work of authorship. For the purposes
- of this License, Derivative Works shall not include works that remain
- separable from, or merely link (or bind by name) to the interfaces of,
- the Work and Derivative Works thereof.
-
- "Contribution" shall mean any work of authorship, including
- the original version of the Work and any modifications or additions
- to that Work or Derivative Works thereof, that is intentionally
- submitted to Licensor for inclusion in the Work by the copyright owner
- or by an individual or Legal Entity authorized to submit on behalf of
- the copyright owner. For the purposes of this definition, "submitted"
- means any form of electronic, verbal, or written communication sent
- to the Licensor or its representatives, including but not limited to
- communication on electronic mailing lists, source code control systems,
- and issue tracking systems that are managed by, or on behalf of, the
- Licensor for the purpose of discussing and improving the Work, but
- excluding communication that is conspicuously marked or otherwise
- designated in writing by the copyright owner as "Not a Contribution."
-
- "Contributor" shall mean Licensor and any individual or Legal Entity
- on behalf of whom a Contribution has been received by Licensor and
- subsequently incorporated within the Work.
-
- 2. Grant of Copyright License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- copyright license to reproduce, prepare Derivative Works of,
- publicly display, publicly perform, sublicense, and distribute the
- Work and such Derivative Works in Source or Object form.
-
- 3. Grant of Patent License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- (except as stated in this section) patent license to make, have made,
- use, offer to sell, sell, import, and otherwise transfer the Work,
- where such license applies only to those patent claims licensable
- by such Contributor that are necessarily infringed by their
- Contribution(s) alone or by combination of their Contribution(s)
- with the Work to which such Contribution(s) was submitted. If You
- institute patent litigation against any entity (including a
- cross-claim or counterclaim in a lawsuit) alleging that the Work
- or a Contribution incorporated within the Work constitutes direct
- or contributory patent infringement, then any patent licenses
- granted to You under this License for that Work shall terminate
- as of the date such litigation is filed.
-
- 4. Redistribution. You may reproduce and distribute copies of the
- Work or Derivative Works thereof in any medium, with or without
- modifications, and in Source or Object form, provided that You
- meet the following conditions:
-
- (a) You must give any other recipients of the Work or
- Derivative Works a copy of this License; and
-
- (b) You must cause any modified files to carry prominent notices
- stating that You changed the files; and
-
- (c) You must retain, in the Source form of any Derivative Works
- that You distribute, all copyright, patent, trademark, and
- attribution notices from the Source form of the Work,
- excluding those notices that do not pertain to any part of
- the Derivative Works; and
-
- (d) If the Work includes a "NOTICE" text file as part of its
- distribution, then any Derivative Works that You distribute must
- include a readable copy of the attribution notices contained
- within such NOTICE file, excluding those notices that do not
- pertain to any part of the Derivative Works, in at least one
- of the following places: within a NOTICE text file distributed
- as part of the Derivative Works; within the Source form or
- documentation, if provided along with the Derivative Works; or,
- within a display generated by the Derivative Works, if and
- wherever such third-party notices normally appear. The contents
- of the NOTICE file are for informational purposes only and
- do not modify the License. You may add Your own attribution
- notices within Derivative Works that You distribute, alongside
- or as an addendum to the NOTICE text from the Work, provided
- that such additional attribution notices cannot be construed
- as modifying the License.
-
- You may add Your own copyright statement to Your modifications and
- may provide additional or different license terms and conditions
- for use, reproduction, or distribution of Your modifications, or
- for any such Derivative Works as a whole, provided Your use,
- reproduction, and distribution of the Work otherwise complies with
- the conditions stated in this License.
-
- 5. Submission of Contributions. Unless You explicitly state otherwise,
- any Contribution intentionally submitted for inclusion in the Work
- by You to the Licensor shall be under the terms and conditions of
- this License, without any additional terms or conditions.
- Notwithstanding the above, nothing herein shall supersede or modify
- the terms of any separate license agreement you may have executed
- with Licensor regarding such Contributions.
-
- 6. Trademarks. This License does not grant permission to use the trade
- names, trademarks, service marks, or product names of the Licensor,
- except as required for reasonable and customary use in describing the
- origin of the Work and reproducing the content of the NOTICE file.
-
- 7. Disclaimer of Warranty. Unless required by applicable law or
- agreed to in writing, Licensor provides the Work (and each
- Contributor provides its Contributions) on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied, including, without limitation, any warranties or conditions
- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
- PARTICULAR PURPOSE. You are solely responsible for determining the
- appropriateness of using or redistributing the Work and assume any
- risks associated with Your exercise of permissions under this License.
-
- 8. Limitation of Liability. In no event and under no legal theory,
- whether in tort (including negligence), contract, or otherwise,
- unless required by applicable law (such as deliberate and grossly
- negligent acts) or agreed to in writing, shall any Contributor be
- liable to You for damages, including any direct, indirect, special,
- incidental, or consequential damages of any character arising as a
- result of this License or out of the use or inability to use the
- Work (including but not limited to damages for loss of goodwill,
- work stoppage, computer failure or malfunction, or any and all
- other commercial damages or losses), even if such Contributor
- has been advised of the possibility of such damages.
-
- 9. Accepting Warranty or Additional Liability. While redistributing
- the Work or Derivative Works thereof, You may choose to offer,
- and charge a fee for, acceptance of support, warranty, indemnity,
- or other liability obligations and/or rights consistent with this
- License. However, in accepting such obligations, You may act only
- on Your own behalf and on Your sole responsibility, not on behalf
- of any other Contributor, and only if You agree to indemnify,
- defend, and hold each Contributor harmless for any liability
- incurred by, or claims asserted against, such Contributor by reason
- of your accepting any such warranty or additional liability.
-
- END OF TERMS AND CONDITIONS
-
- APPENDIX: How to apply the Apache License to your work.
-
- To apply the Apache License to your work, attach the following
- boilerplate notice, with the fields enclosed by brackets "[]"
- replaced with your own identifying information. (Don't include
- the brackets!) The text should be enclosed in the appropriate
- comment syntax for the file format. We also recommend that a
- file or class name and description of purpose be included on the
- same "printed page" as the copyright notice for easier
- identification within third-party archives.
-
- Copyright [yyyy] [name of copyright owner]
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
Copied: CalendarServer/trunk/LICENSE.txt (from rev 12409, CalendarServer/trunk/LICENSE)
===================================================================
--- CalendarServer/trunk/LICENSE.txt (rev 0)
+++ CalendarServer/trunk/LICENSE.txt 2014-01-23 01:15:50 UTC (rev 12425)
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
Deleted: CalendarServer/trunk/README
===================================================================
--- CalendarServer/trunk/README 2014-01-23 01:15:05 UTC (rev 12424)
+++ CalendarServer/trunk/README 2014-01-23 01:15:50 UTC (rev 12425)
@@ -1,112 +0,0 @@
-Getting Started
-===============
-
-This is the core code base for the Calendar and Contacts Server, which
-is a CalDAV, CardDAV, WebDAV, and HTTP server.
-
-For general information about the server, see:
-
- http://www.calendarserver.org/
-
-
-Copyright and License
-=====================
-
-Copyright (c) 2005-2014 Apple Inc. All rights reserved.
-
-This software is licensed under the Apache License, Version 2.0. The
-Apache License is a well-established open source license, enabling
-collaborative open source software development.
-
-See the "LICENSE" file for the full text of the license terms.
-
-
-Quick Start
-===========
-
-**WARNING:** these instructions are for running a server from the
-source tree, which is useful for development.
-These are not the correct steps for running the server in
-deployment or as part of an OS install. You should **not** be using
-the ``run`` script in system startup files (eg. ``/etc/init.d``); it
-does things (like download software) that you don't want to happen in
-that context.
-
-Begin by creating a directory to contain Calendar and Contacts Server
-and all its dependencies:
-
- ::
-
- mkdir ~/CalendarServer
- cd CalendarServer
-
-Next, check out the source code from the SVN repository. To check out
-the latest trunk code:
-
- ::
-
- svn co http://svn.calendarserver.org/repository/calendarserver/CalendarServer/trunk/ CalendarServer
-
-The server requires a number of libraries in order to operate, which
-will need to be placed as peers of the source directory. The ``run``
-script in the sources will automatically download or check out the
-appropriate libraries and build them for you:
-
- ::
-
- cd CalendarServer
- ./run -s
-
-The result will be a set of directories, including the CalendarServer
-source directory in your original empty directory:
-
- ::
-
- % ls -1 ~/CalendarServer
- CalDAVTester
- CalendarServer
- PyGreSQL-4.0
- ...
-
-Before you can run the server, you need to set up a configuration file
-for development. There is a provided test configuration that you can
-use to start with, called ``caldavd-test.plist``. Copy this to
-``caldavd-dev.plist``, which the server will use in development:
-
- ::
-
- cp ./conf/caldavd-test.plist ./conf/caldavd-dev.plist
-
-You will need to choose a "directory service" to use to populate your
-server's principals (users, groups and resources). A directory
-service provides the Calendar and Contacts Server with information
-about these principals. Some of the directory services which are
-supported by the Calendar and Contacts Server include:
-
- * ``XMLDirectoryService``: this service is configurable via an XML
- file that contains principal information. The file
- ``conf/auth/accounts.xml`` provides an example principals
- configuration.
-
- * ``OpenDirectoryService``: this service uses Apple's OpenDirectory
- client (which in turn uses LDAP, Active Directory, etc.) to obtain
- principal information.
-
-The ``caldavd-test.plist`` configuration uses ``XMLDirectoryService``
-by default, set up to use ``conf/auth/accounts-test.xml``. This is a
-generally useful configuration for development and testing.
-
-This file contains a user principal, named ``admin``, with password
-``admin``, which is set up (in ``caldavd-test.plist``) to have
-administrative permissions on the server.
-
-You can then run the server as follows:
-
- ::
-
- ./run
-
-The server should then start up and bind to port 8008 for HTTP and
-8443 for HTTPS. You should then be able to connect to the server
-using your web browser (eg. Safari, Firefox) or with a CalDAV client
-(eg. iCal).
Copied: CalendarServer/trunk/README.rst (from rev 12409, CalendarServer/trunk/README)
===================================================================
--- CalendarServer/trunk/README.rst (rev 0)
+++ CalendarServer/trunk/README.rst 2014-01-23 01:15:50 UTC (rev 12425)
@@ -0,0 +1,112 @@
+Getting Started
+===============
+
+This is the core code base for the Calendar and Contacts Server, which
+is a CalDAV, CardDAV, WebDAV, and HTTP server.
+
+For general information about the server, see:
+
+ http://www.calendarserver.org/
+
+
+Copyright and License
+=====================
+
+Copyright (c) 2005-2014 Apple Inc. All rights reserved.
+
+This software is licensed under the Apache License, Version 2.0. The
+Apache License is a well-established open source license, enabling
+collaborative open source software development.
+
+See the "LICENSE" file for the full text of the license terms.
+
+
+Quick Start
+===========
+
+**WARNING:** these instructions are for running a server from the
+source tree, which is useful for development.
+These are not the correct steps for running the server in
+deployment or as part of an OS install. You should **not** be using
+the ``run`` script in system startup files (eg. ``/etc/init.d``); it
+does things (like download software) that you don't want to happen in
+that context.
+
+Begin by creating a directory to contain Calendar and Contacts Server
+and all its dependencies:
+
+ ::
+
+ mkdir ~/CalendarServer
+ cd CalendarServer
+
+Next, check out the source code from the SVN repository. To check out
+the latest trunk code:
+
+ ::
+
+ svn co http://svn.calendarserver.org/repository/calendarserver/CalendarServer/trunk/ CalendarServer
+
+The server requires a number of libraries in order to operate, which
+will need to be placed as peers of the source directory. The ``run``
+script in the sources will automatically download or check out the
+appropriate libraries and build them for you:
+
+ ::
+
+ cd CalendarServer
+ ./run -s
+
+The result will be a set of directories, including the CalendarServer
+source directory in your original empty directory:
+
+ ::
+
+ % ls -1 ~/CalendarServer
+ CalDAVTester
+ CalendarServer
+ PyGreSQL-4.0
+ ...
+
+Before you can run the server, you need to set up a configuration file
+for development. There is a provided test configuration that you can
+use to start with, called ``caldavd-test.plist``. Copy this to
+``caldavd-dev.plist``, which the server will use in development:
+
+ ::
+
+ cp ./conf/caldavd-test.plist ./conf/caldavd-dev.plist
+
+You will need to choose a "directory service" to use to populate your
+server's principals (users, groups and resources). A directory
+service provides the Calendar and Contacts Server with information
+about these principals. Some of the directory services which are
+supported by the Calendar and Contacts Server include:
+
+ * ``XMLDirectoryService``: this service is configurable via an XML
+ file that contains principal information. The file
+ ``conf/auth/accounts.xml`` provides an example principals
+ configuration.
+
+ * ``OpenDirectoryService``: this service uses Apple's OpenDirectory
+ client (which in turn uses LDAP, Active Directory, etc.) to obtain
+ principal information.
+
+The ``caldavd-test.plist`` configuration uses ``XMLDirectoryService``
+by default, set up to use ``conf/auth/accounts-test.xml``. This is a
+generally useful configuration for development and testing.
+
+This file contains a user principal, named ``admin``, with password
+``admin``, which is set up (in ``caldavd-test.plist``) to have
+administrative permissions on the server.
+
+You can then run the server as follows:
+
+ ::
+
+ ./run
+
+The server should then start up and bind to port 8008 for HTTP and
+8443 for HTTPS. You should then be able to connect to the server
+using your web browser (eg. Safari, Firefox) or with a CalDAV client
+(eg. iCal).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20140312/43116709/attachment.html>
More information about the calendarserver-changes
mailing list