++++++++++++++++++++++++++++
Python Paste Developer Guide
++++++++++++++++++++++++++++

Hi.  Welcome to Paste.  I hope you enjoy your stay here.

I hope to bring together multiple efforts here, for Paste to support
multiple frameworks and directions, while presenting a fairly
integrated frontend to users.  How to do that?  That's an open
question, and this code is in some ways an exploration.

There's some basic principles:

* Keep stuff decoupled.

* Must be testable.  Of course tested is even better than testable.

* Use WSGI standards for communication between decoupled libraries.

* When possible, use WSGI as a wrapper around web-neutral libraries.
  For instance, the configuration is a simple library, but the WSGI
  middleware that puts the configuration in place is really really
  simple.  If it could be used outside of a web context, then having
  both a library and middleware form is good.

* Entry into frameworks should be easy, but exit should also be easy.
  Heterogeneous frameworks and applications are the ambition.  But we
  have to get some messiness into Paste before we can try to resolve
  that messiness.

* When all is said and done, users should be able to ignore much of
  what we've done and focus on writing their applications, and Stuff
  Just Works.  Documentation is good; stuff that works without user
  intervention is better.

Developer Info
==============

Mostly, if there's a problem we can discuss it and work it out, no one
is going to bite your head off for committing something.

* Framework-like things should go in subpackages.  The top level is
  only for things that are lower-level than a framework.  

* Integrating external servers and frameworks is also interesting, but
  if someone else is maintaining the code elsewhere you shouldn't
  import their work into the repository -- it'll just cause
  confusion.  Create a script to pull in their work or something, and
  check that in.

* Tests are good.  We use py.test_, because it is simple.  I want to
  use doctests too, but the infrastructure isn't really there now --
  but please feel free to use those too.  ``unittest`` is kind of
  annoying, and py.test is both more powerful and easier to write for.
  Tests should go in a ``tests/`` subdirectory.
  ``paste.tests.fixture`` contains some convenience functions for
  testing WSGI applications and middleware.
  
.. _py.test: http://codespeak.net/py/current/doc/test.html

* If something is really experimental, put it in your home directory,
  or make a branch in your home directory.  You can make a home
  directory for yourself, in ``http://svn.w4py.org/home/username``.

* Not everything in the repository or even in the trunk will
  necessarily go into the release.  The release should contain stuff
  that is tested, documented, and useful.  Each module or feature also
  needs a champion -- someone who will stand by the code, answer
  questions, etc.  It doesn't have to be the original developer, but
  there has to be *someone*.  So when a release is cut, if some
  modules don't fulfill that they may be left out.

* Try to keep to the `Style Guidelines`_.  But if you are bringing in
  outside work, don't stress out too much about it.  Still, if you
  have a choice, follow that.  Those guidelines are meant to represent
  conventional Python style guides, there's nothing out of the normal
  there.

.. _Style Guidelines: StyleGuide.html