Renamed WSGIKit to Paste

1 files changed, 80 insertions, 0 deletions

diff --git a/docs/DeveloperGuidelines.txt b/docs/DeveloperGuidelines.txt
new file mode 100644
index 0000000..8ff8122
--- /dev/null
+++ b/docs/DeveloperGuidelines.txt
@@ -0,0 +1,80 @@
++++++++++++++++++++++++
+WSGIKit Developer Guide
++++++++++++++++++++++++
+
+Hi.  Welcome to WSGIKit.  I hope you enjoy your stay here.
+
+I hope to bring together multiple efforts here, for WSGIKit 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 WSGIKit 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.
+  ``wsgikit.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
+