#summary How to get started with Melange
#labels Featured,Phase-Guidelines,Contents-Draft,Importance-Featured

= Prerequisites =

Melange is a web application that runs on
[http://code.google.com/appengine/ Google App Engine].  Google App Engine requires
Python 2.5 or later.  Please follow the instructions for your development platform
[http://www.python.org/download/releases/2.5.2/ here] to install Python.

= Checking Out the Code =

Follow the instructions [http://code.google.com/p/soc/source/checkout here] to create an SVN working copy by checking out the Melange source code.  If you are not yet a
[ContributionReviews#Committers committer] to the Melange project, you will need to
follow the instructions for checking out a read-only working copy.

= Running the Code =

Change directories into your SVN working copy (into the `trunk/` directory if you have
customized your working copy).  There is currently no _build_ step for the Melange web
application (though one will soon be needed in order to upload Melange to a Google
App Engine instance).  However, you will need to create your own `app/app.yaml` file from
the existing `app/app.yaml.template` file.  On a UNIX system, in the working copy using
shell commands, this can be done with something like:

{{{
cp app/app.yaml.template app/app.yaml
}}}

Then, edit the newly-created `app.yaml` file with your favorite editor, changing these
lines:

{{{
# TODO(proto): uncomment and supply a Google App Engine application instance
# application: FIXME
}}}

to something like:

{{{
application: your-app-engine-name
}}}

where `your-app-engine-name` is the name of one of your Google App Engine slots (or
just some made-up string if you only want to run the `dev_appserver.py` that comes
with the
[http://code.google.com/appengine/downloads.html Google App Engine SDK]).

The Melange web application can the be started from the SVN working copy with this
command line (since `thirdparty/google_appengine` is checked into the Melange SVN
repository because tests need it to run):

{{{
thirdparty/google_appengine/dev_appserver.py app
}}}

Melange should then be running on [http://localhost:8080/ your workstation on port 8080].

= Contributing =

There are a number of ways that you can contribute to the Melange project.

== Discussion ==

If you are interested in contributing to the Melange project, please join our
[MailingListsGuidelines#General_discussion_list general discussion mailing list].
Also,feel free to join us [IrcChannelGuidelines on IRC].

== User Stories, Feature Requests, and Mock-Ups ==

If you are a past mentor or student participant in GSoC or GHOP but do not have the time
to contribute patches to Melange, we can still use your help.  While there is some code
already submitted for Melange, large parts of the web application are not yet defined.
Please consider writing up a feature request, [UserStories User Story], or even
creating a [http://soc.googlecode.com/svn/trunk/mockups/sitehome.html mock-up] of
something you would like to see in Melange.  You can also take a look at the existing
[http://code.google.com/p/soc/issues/list?q=type:Story User Stories] and add your
comments and suggestions.

== Patches ==

[ContributionReviews#Patches Patches] to the code are also welcome,
[ContributionReviews#Suggested_patches_from_casual_contributors even from non-committers].

= Gory Details =

If you enjoy reading dry design documents, you can find some of them
[MelangeIntro here] and [SoCOverview here].  Please bear in mind that this effort is in its very early stages and is being carried out in public view.  Much of the documentation is very incomplete and will evolve over time.