Guidelines for Gallery2 Developers
----------------------------------

This is a set of notes that G2 developers should read before they
start doing serious work on G2.  Right now it's just a brain dump of
things that I want to remember.  We should flesh it out as we go.

0. Read and obey the Gallery Coding Standards!
   http://gallery.menalto.com/modules.php?op=modload&name=GalleryDocs&file=index&req=viewarticle&artid=19

1. Always do an HTTP redirect after receiving a HTTP POST or GET where we
   actually take an action.

   Whenever we actually make a change to the database or the
   filesystem as a result of an HTTP post or GET, we want to make sure
   that we redirect the user to a safe page.  This way, if the user
   hits the reload button, they will not trigger the action gain!  All
   of the core views do this and can be used as an example for ways to
   make sure that it is done correctly.

2. After making any text changes to the system, re-build all translations!

   % cd lib/tools/po
   % perl update-all-translations.pl

   This will extract new strings.raw files and generate new
   messages.po files, but only if there's an actual change!
   Translators can monitor their .po files to know when they need to
   update the translations they own.  Changes to the strings.raw files
   will provide a clue as to what actually changed.

3. Use single quotes instead of double quotes where possible.  

   PHP must interpret the entire contents of anything inside double
   quotes to see if it has any variables that need to be evaluated.
   Use single quotes when you don't have any variables inside the
   string.

4. GalleryStorage is backend agnostic.

   The GalleryStorage API makes no assumptions about how the back end
   works.  Therefore, you can not make any references to database
   tables, indexes, columns, rows, etc.  Instead you must refer to
   classes and members in the API.

5. Rebuild interfaces and database schemas whenever you change an
   entity or map's G2 members.

   A G2 member is a member which has a "@g2" XML snippet in its phpdoc
   variable comment.  We use that to generate the interface files
   associated with every class and map, and also to generate the SQL
   database definitions.  Before G2 1.0 is shipped, we can mess with
   these as much as we want (while respecting whatever change control
   policies we set in alpha and beta).  But after G2 1.0 ships, we
   must change the entity/map schema version number and create entity
   migration XML files whenever we change entity members.