Getting Started with AllForGood: modifying the core code

Downloading and running a local server

  1. (10mins) install Google App Engine (instructions).
    requires Python; most operating systems supported.
  2. [if needed] (1 hour) install a Subversion client. Subversion is pre-installed on most unix/linux systems.
  3. Check out a copy of the source code (instructions). To check out the repository in read-only mode:
       svn checkout http://allforgood.googlecode.com/svn/trunk/
   allforgood-read-only
    To check out the repository with write permissions (you will need to be a member of the project for code hosting): 
       svn checkout https://allforgood.googlecode.com/svn/trunk/
   allforgood --username gmail.user
    When prompted for password, use the one automatically generated for your Gmail account (to which you'll need to be logged in) here.
  4. create a frontend/private_keys.py file and fill it with your private keys:
           DEFAULT_FACEBOOK_SECRET = '62354267436743487347364873473'
       # Secret keys unique to our domains
       FACEBOOK_SECRETS = {
         'yourdomain.com': '7q64373264736487364873642873648734',
       }
  5. To start appengine locally, from the root of the Footprint repository checkout issue:
    ../google_appengine/dev_appserver.py frontend/
  6. Load the app in a browser with this address: http://localhost:8080/

    Tip: If this fails, you may need to add "-a <ip address>" to the dev_appserver.py command above.

HTML/CSS/JS and Django Templates

The site is an 'AJAX' app coded in HTML/CSS/JS. The directories are frontend/css, frontend/html, frontend/js and frontend/images. The code is fairly self-explanatory, with these notes:
  • login_bar.html -- this is loaded asynchronously, to avoid blocking search results from loading before user login is checked.
  • /ui_snippets -- this is the actual search call, and should be executed ASAP, in parallel with the rest of the page loading.
The frontend template files use Django inheritance to simplify assembly. The base template file is "base.html", and it defines a number of blocks which can be overridden. One of these blocks is named content_layout, and it occupies the main area of the page, below the header and above the footer.content_layout is overridden inside a layout file (for example, "layout_full.html"). The layout file then defines one of more content blocks, which are overridden by a specific frontend page.

There are two layout files checked in:
  • layout_full.html - exposes a single content block that takes up entire region between header and footer.
  • layout_two_column.html - exposes two content blocks: content_left and content_right. By default the left block takes up 50% of the window. This can be overridden using width_left and width_right
The search results template (templates/search_results.html) uses the two column layout, while the post template (templates/post.html) uses the "full" layout.

The following blocks are exposed by base.html, and can be overridden in any derived template page:
  • css_files: <link> tags for css files to include.
  • js_files: <script> tags for JS files to include.
  • subheader: area below header.
  • prefooter: area above footer.
  • content_layout: the main area inside the body, below the header, or below the subheader if defined. This should only be overridden by layout templates.

Coding Style

We use pylint (available in Ubuntu and other Linux distributions through apt-get/aptitude) as our standard for automatically checking style adherance, and have a custom pylintrc for the project checked into the toplevel directory. To run pylint and automatically pickup our rc file: 
      cd allforgood; pylint path/to/filename.py
The output is parseable e.g. for use in emacs compile-mode.

At this time, we are NOT aiming for 100% compliance-- a score above >=9.0 per file is good enough, but please try to adhere to function/variable naming, indentation and line lengths (to ease code review).

Code Review and Checking in Changes

core team: daniel.berlin@gmail.com, adam.sah@gmail.com, blocksom@gmail.com
  1. For one-time and occasional developers, email footprint-eng@googlegroups.com with a brief description of the changes and a patch file.
  2. for ongoing contributors, first get write access to the repository from one of the core members, then get a code review: /path/to/allforgood/codereview_upload.py %lt;email of primary reviewer%gt;

Deployment to an AppEngine server

You can (and should) deploy your code to your own appengine instance first. Instructions for uploading application are here.

The team's shared development AppEngine instance is named "footprint2009dev". To get deployment access, contact one of the core engineers, above. Please only upload code reviewed, SVN-committed versions of the source code, without any local changes, and upload immediately to avoid conflicts with other developers.

To update the dev environment with changes you've committed to SVN, issue this command from the root of the Footprint repository: 
../google_appengine/appcfg.py update frontend/
Important: Your Gmail account must be listed as a Project Member for appengine, and not just for code hosting, to update environments. If this listing changed recently, you will need to accept the invitation (sent to your Gmail account, of course) before proceeding.

When prompted for email, include your full Gmail address: your.name@gmail.com

When prompted for password, include your Gmail password (not the one provided at code.google.com).

Engineering Glossary:

Since AFG started with google engineers, we've adopted google engineering lingo:
  • Footprint-- the codename for AllForGood (aka "AFG"). We're slowly scrubbing the code and docs, but it'll take a long time, and it's not a priority.
  • CL-- "change list" aka proposed or already-committed set of code changes.
  • code review-- as per google engineering, virtually all submissions are proposed before being committed to the source repository. This is done by having the code read carefully by a person with domain experience with the algorithms, as well as a person (potentially a 2nd reviewer) with experience in the affected code.
  • design doc/review-- as per google engineering, substantial projects require the engineer to publish a paper design, including explanations of the key requirements (technical and product) and how this design meets those requirements, competing solutions and they were rejected, and infrastructure & algorithm choices.
  • P0/P1/P2 bugs-- P0 are blocking, stop-everything-and-fix-it bugs and with no known workaround. P1 are blocking bugs affecting a subset of users, with no known workaround. P2 bugs have workarounds, however hacky/awful. P3 and below are minor annoyances, to be fixed if it's easy, or as part of "fixit" efforts.
  • issue-- synonym for bug.
  • codesite-- synonym for project hosting on code.google.com, i.e. code.google.com/p
  • lg/lgtm/sgtm-- "looks/sounds good to me". LGTM is particularly important, because it is often mentioned in searches, i.e. important to standardize on LGTM for code reviews and other processes.
  • Code Red/Yellow/Green-- codes are used by ops teams to indicate severity+urgency levels for live situations. Code Red is a site outage and takes priority over all other projects, and typically comes with hourly reporting. Code Yellow are ongoing situations (e.g. high latency, long submission queues) for which a subset of the team is 100% allocated to addressing them, and given priority over new features. Code Green is the base state where sleep is allowed.
  • Fixit-- a structure process (typically one full day) where 100% of engineering works on nothing but fixing things under some common theme. examples include docs fixits, bugs fixits, internationalization fixits, performance/latency fixits, etc. Fixits are coordinated top-down from PM and engineering management, with a single eng lead for the day.
Sign in with Facebook, Google, More » | Help