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