Using This Repository
=====================

Hello, and welcome to the colorstudy.com repository.  You are probably
working on the SQLObject project, but this applies to all projects.

Mailing List
------------

sqlobject-cvs@lists.sf.net is the commit mailing list.  You may join
it through http://lists.sourceforge.net/lists/listinfo/sqlobject-cvs

Every attempt I've made to separate out mail from different projects
has failed, so every commit to the colorstudy.com repository will send
a message, even if it's not to SQLObject.  Oh well.  If you are
actively developing with SQLObject, I highly recommend subscribing to
this list.  If you are developing on the main or maintenance branch of
SQLObject, you really should be subscribed to the list to keep track
of what people are doing.

sqlobject-discuss@lists.sf.net is the discussion list.  Substantive
work should be discussed there, particularly before committing it to a
trunk or maintenance branch.

Community, Decision Making
--------------------------

Some changes to SQLObject should be taken more seriously than others.
Some changes you should worry about:

* Backward-incompatible changes.

* Non-enhancement features -- that is, features that aren't an
  extension of current features, but are a whole new line of
  development.

* Changes that aren't applicable to all database backends.

* Changes that bring SQLObject outside of the realm of relational
  databases.  (Maybe you should make a separate library that just uses
  SQLObject?)

If you feel compelled to make one of these changes, please start it in
a private branch.  If you still feel compelled after finishing it,
please discuss it on the mailing list.  Also be aware that radical
changes can make releases difficult -- it would be helpful to prepare
for a new (more incremental) release before you push for a radical
change.  It is even better if you can find incremental features in
your suggested change that can be applied in isolation.  

Some changes that you shouldn't make:

* Changes that don't include extensive unit tests.

* Visible changes that aren't noted in News.txt.

* Changes that make the documentation out of sync with the code.
  Change the documentation with your code!  Otherwise no one will even
  be able to appreciate your change.

* Changes that haven't been tested on at least two backends.  Though
  really I recommend testing on at least MySQL, Postgres, and SQLite.
  The proprietary database backends may break, and that's just life.
  Firebird and MaxDB/SAPDB are a bit harder to administer, even if
  they are open source, so if you don't keep up with them I
  understand.  You might want to solicit feedback from users of those
  databases when you make changes that might effect compatibility.

Changes you shouldn't worry about:

* Anything you put in your home directory.  If you don't have a home
  directory, make one for yourself in ``/home/username``.  This is the
  place for you to do whatever you want, while also allowing other
  people to see your experiments.  Don't worry about documentation,
  tests, or whatever.  Unless you want to.

* Anything in private branches in your home directory.  Feel free to
  branch whenever you want.  In Subversion, you simply copy
  directories to make a branch, like ``cp trunk/SQLObject
  home/me/my-SQLObject-branch``

* Adding tests.  More tests are more good.  It's okay if the test
  doesn't pass, if you really think it should -- this is the best kind
  of bug tracking.  If it turns out not to be a bug, we can discuss it
  on the mailing list and remove the test later, so it's no big deal.

* Adding documentation.  Of course, be careful to document stuff
  accurately -- don't add documentation to the trunk that applies only
  to your branch.  Also, try to use the snippet mechanism I am using,
  which allows you to put your code in separate files -- if at all
  possible, try to make that file executable so you can test your
  sample code.  Please keep all documentation in the restructured text
  format.

* Moving things to and from the wiki (http://wiki.sqlobject.org).  The
  wiki accepts restructured text, so pages on the wiki can go into the
  documentation, and vice versa.  I'm not sure what their roles really
  are, so whatever you think makes sense.  At some point the wiki
  might become the dominant form of documentation (maybe I'll make a
  Subversion backend, and then they'll both be the same thing).