DeveloperGuideGHC11

Getting Started

You can develop on Linux, or Mac OS, or Windows-with-Cygwin.

Step 1. Get tools

You will probably be happiest if you do these steps in order.

Python 2.5.x or 2.6.x (your system may already have this; try running "python" or "python2.5" to check)

All platforms: Download here and install
Mac OS X: the pre-installed Python binaries are at /System/Library/Frameworks/Python.framework/Versions/2.x/bin/python2.x and are symlinked from /usr/bin/python2.x. If you downloaded and installed a new version, it will be in /Library/Frameworks rather than /System/Library/Frameworks, and you'll need to ln -s /Library/Frameworks/Python.framework/Versions/2.5/bin/python /usr/bin/python2.5

Setuptools 0.6c11 and EasyInstall (your system may already have this; try running "easy_install" or "easy_install-2.5" to check)

All platforms: Download, then tar xvfz and sudo python2.5 setup.py install.

PIL 1.1.7 — optional, only needed if you want to test photo uploading locally

All platforms: Download then tar xvfz and sudo python2.5 setup.py install.
If you have trouble installing PIL 1.1.7 with Python 2.5.2, try switching to Python 2.5.4.

App Engine SDK 1.5.2 or higher (but not 1.6) for Python

All platforms: Download the Linux zip file (regardless of your platform) from google_appengine_1.5.4.zip and unzip in your home directory.

Nose — for running unit tests

All platforms: sudo easy_install-2.5 nose

Mercurial 1.6.4 — for revision control

Linux: Download, then tar xvfz and sudo make install.
Mac OS 10.5: Download, double-click, and install.
Mac OS 10.6: Download, double-click, and install.

Gettext — for internationalization

Linux: sudo apt-get install gettext
Mac OS 10.5: Download, double-click, and install.
Mac OS 10.6: Download, double-click, and install.
Mac OS 10.7: Download, double-click, and install.

Step 2. Get the code

Make a local clone of the code repository with this command. First create a separate local directory to hold code, for example, a directory called "pf" (henceforth referred to as the "application directory"):

mkdir pf

hg clone https://googlepersonfinder.googlecode.com/hg pf

Create a .hgrc file in your HOME directory (or on a Windows system in %USERPROFILE%\Mercurial.ini) containing the following 2 lines:

[ui]
username = Yourfirstname Yourlastname <youremailaddress>

Questions about Mercurial? Check out the quickstart guide.

Step 3. Initialize the data in the app

All the following commands should be done from the application directory (the pf directory we created in the previous step).

cd pf

In one terminal, start a local server with this command:

dev_appserver.py app # Brings up a local dev_appserver, serving on localhost:8080 by default

With the app server running, open a separate terminal and connect to the app's datastore with the command:

tools/console localhost:8080 # Connects to localhost port 8080

At the Python prompt that appears, enter this command to set up the datastore:

>>> setup_datastore()

Step 4. Try the app!

Now you should be able to use the app by going to http://localhost:8000/ in a browser.

You can also run tests like this:

tools/all_tests

You may see some warning about the version of Python but it is okay to ignore it now.

If you would like to contribute code, please see GHC11 How To Develop.

Step 5. (optional) Configure your instance

The Person Finder application can run several instances. There is usually one instance per current crisis. Each instance can be customized with a list of interface languages, announcements, and so on.

How to create a new instance

When running on localhost, you can create a new instance by adding a subdomain to the python configuration file: tools/setup.py

If your application is deployed on appengine, you can access to an admin UI at http://yourapplication.appspot.com/admin

Top

How To Develop

We use Mercurial (hg) for revision control. If you're new to Mercurial, try the tutorial at http://hginit.com/. Mercurial is a distributed RCS, which means that your local machine gets a complete copy of the repository with all its history, and you can commit changes locally before pushing them to the main repository.

Making local changes

Before you start making a new set of changes:

	`hg pull; hg update ghc-dev`	# Brings your local repository up to date to the ghc-dev release branch
	`hg branch username-feature`	# Makes a new branch for your changes

Your branch name should consist of your username, a hyphen, and a short identifier that describes your change.

Now you can write code, edit, test, etc. If you are adding or removing files, use hg add or hg rm. If you are moving content from one file to another, use hg cp or hg mv.
You can see the files your modified through hg status.

Testing your changes

There are two kinds of tests. When you make a significant change, please add tests for it (see HowToWriteTests for details).

Run the unit tests with this command:

	`tools/unit_tests`	# Takes about 3 seconds

Run the system tests with this command:

	`tools/server_tests`	# Starts the app server on port 8081 and makes requests to it
	# Takes about 3 minutes

You can also run all the tests with tools/all_tests.

Merging in changes from others to prepare for code review

You can first look at your changes:

	`hg status`	# Lists all files modified, created, removed.
`hg diff`	# Display diffs on all modified files.

Other changes can continue to happen on the ghc-dev branch while you are working. So, you'll need to merge in these changes before you do the final round of testing. To merge in these changes:

	`hg commit`	# Commits your pending changes locally.
`hg pull`	# Pulls down any new changes from the main repository to your local repository
`hg merge ghc-dev`	# Merges changes from the ghc-dev branch into your branch
`hg commit`	# Commits the merge locally on your branch

hg commit will bring up an editor for you to enter a commit message. If you don't enter a commit message, the commit will be cancelled.

The merge command operates on two committed changesets (which is why you have to commit your local changes first) and produces a new changeset (which you then have the opportunity to inspect before committing).

After merging, rerun your tests to make sure merge was fine.

Requesting a code review

When you have code that is tested and works, request a code review by running the rietveld script like this:

	`tools/rietveld-ghc reviewer`

(reviewer should be the Google contact listed on the bug/issue you are working on. You may specify more than one reviewer by separating email addresses with commas.)

At some point, it will ask for a user and password, just leave them both empty and it will go through.

Note: If you are asked to enter "Password for --send_mail", make sure there is a .email file in your home directory with the account you used to sign into code.google.com.

This will produce a diff from the ghc-dev branch to your branch and upload it to Rietveld, an open-source review tool. The reviewer or reviewers will receive e-mail from you directing them to a page where they can browse your changes and make comments, and everyone can send comments back and forth.

If your reviewer asks you to make some changes, you can do those changes locally, run the tests again, and then run rietveld again. This will update the existing code review with a new patch.

You can have multiple branches in progress in your local repository, if you need to, and switch among them with hg update. Each time you run rietveld, it will detect the branch you are working in, and will either create a new code review or update the existing code review.

Code has been reviewed and is ready to be added to ghc-dev branch

When your reviewer approves the changes, Then you need to send your patch to the reviewer which will incorporate it in the ghc-dev branch. For this, you need to create a bundle of your code using

	`hg outgoing`	# shows changeset which are not in ghc-dev branch
	`hg bundle -r your_branch_name --base ghc-dev your_filename.hg`	# creates a compressed changegroup file with these changesets

Send your_filename.hg by email to the Google contact on the issue (i.e., your code reviewer) which will incorporate them into the ghc-dev branch.

Then you can update and return to the ghc-dev branch like this: