app/README

   1 = WHAT BELONGS IN trunk/app =
   2
   3 trunk/app should contain only the files needed for the actual Google App
   4 Engine application "image".  Support code that is not part of the application
   5 image belongs elsewhere, such as in trunk/scripts, for example.
   6
   7 = THIRD PARTY CODE =
   8
   9 Third-party code that is *not* part of the application image (the Google App
  10 Engine SDK in trunk/thirdparty/google_appengine, for example) belongs in
  11 trunk/thirdparty (see also trunk/thirdparty/README).
  12
  13 Third-party code that is part of the application image is placed in a package
  14 subdirectory in trunk/app, such as trunk/app/django, for example.
  15
  16 If the third-party package is a single Python source file, place the code in
  17 trunk/app/<package>/__init__.py, so that it can simply be imported using,
  18 for example:
  19
  20 import feedparser
  21
  22 (The trunk/app/feedparser package is a good example of this approach.)
  23
  24 == THIRD PARTY LICENSES ==
  25
  26 Third-party code must also include a license text file, named LICENSE or
  27 COPYING, in the package subdirectory.  If the third-party package subdirectory
  28 is maintained automatically with a tool such as svn_load_dirs.pl (which
  29 removes files, such as license text files, that were added later to the
  30 "target" directory), place the license text file in the trunk/app directory
  31 and add the package name as a suffix (LICENSE.django is an example of this
  32 case).
  33
  34 = CREATING AN OFFICIAL RELEASE =
  35
  36 == CREATING THE RELEASE CANDIDATE BRANCH AND TAGGING A RELEASE ==
  37
  38 Steps (currently done by hand, but too be scripted in the future) to make
  39 a release:
  40
  41 1) Set the "version:" field in the app.yaml.template file to a "release
  42    candidate" release string.  Version strings cannot contain dots
  43    (periods) and have some other restrictions.  As a result, the format
  44    of the release-candidate "version:" field needs to be:
  45
  46      A-B-YYYYMMDD
  47
  48    where:
  49    * A is a major number (currently '0' until at least GSoC functionality
  50      is completely implemented)
  51    * B is a (possibly multi-digit) minor number that is increased whenever
  52      there is a major increase in functionality (some major GSoC or GHOP
  53      feature, e.g. student sign-ups and proposals, is implemented)
  54    * YYYY is the four digit year of the release date
  55    * MM is the (always) two digit month of the release date (zero-padded)
  56    * DD is the (always) two digit day of the release date (zero-padded)
  57
  58 2) Commit this file *by itself* in its own commit.
  59
  60 3) Use 'svn cp' to create a release branch of /trunk/ in /branches/ with
  61    exactly the same name as the contents of the "version:" field in the
  62    app.yaml.template file.  Branch on the specific revision of the commit
  63
  64 4) Finalize the release candidate branch for a push to the live web site.
  65    Use 'svn cp' to create a tag in /tags/ with exactly the same name as the
  66    contents of the "version:" field in the app.yaml.template file.  Specify
  67    the *specific revision* of the commit in step #2 above.
  68
  69 Step #4 might actually be delayed for one or more patch releases, once there
  70 is some sort of User Acceptance Testing (UAT) checklist for a release
  71 candidate, because defects would be patched in the release candidate branch
  72 one or more times before an actual release is tagged.  See the next section
  73 for details.
  74
  75 == PATCHING AND RE-RELEASING AN EXISTING RELEASE CANDIDATE BRANCH ==
  76
  77 To re-release a previously-tagged release branch after a patch for a push to
  78 the live web site:
  79
  80 1) Increment the "patch suffix" of the "version:" field value to the next
  81    integer (for example, "p1" becomes "p2"), or append "p1" to the end of
  82    the existing string if this is the first patch release (so the first tagged
  83    patch release will always be "p1").  For example:
  84
  85      A-B-YYYYMMDD becomes A-B-YYYYMMDDp1
  86
  87    and:
  88
  89      A-B-YYYYMMDDp1 becomes A-B-YYYYMMDDp2
  90
  91    etc.
  92
  93 2) Commit this file *by itself* in its own commit (after the last batch
  94    of patches being made to the existing /branches/ release branch).
  95
  96 3) Use 'svn cp' to create a tag in /tags/ with exactly the same name as the
  97    contents of the new, patched "version:" field in the app.yaml.template
  98    file.  Specify the *specific revision* of the commit in step #2 above.
  99