README

A. 'TASKS' INTRODUCTION/GOALS
================================================================================

'Tasks' is a rich-internet application for tracking personal or team tasks.
The 'Tasks' GUI runs on desktop and iPad browsers and is particularly useful
for managing Agile software development.

See a quick video overview at:

http://www.youtube.com/watch?v=6egjJw_RS1g

Check out a full demo instance at:

http://tasks-demo.appspot.com
Login as 'SG' no password

Tasks also runs in 'ToDo' mode (this is useful to manage a list of things to do,
personal or for a team).  An instance built in this mode is available at:

http://tasks.sproutcore.com

'Tasks' consists of a SproutCore-based GUI and REST-based Servers.
Persevere and Google App Engine (GAE) Servers are supported out-of-the-box.

I started the 'Tasks' project in June 2009 with the following goals:

1) To become a comprehensive sample application that goes beyond  "hello world"
   examples (like "clock") and snippets showing off facets of SproutCore
   (like "drag").  I want to use 'Tasks' to learn SproutCore and showcase its
   capabilities on the desktop and iPad via a single application.

2) To illustrate how to engineer a non-trivial application using artifacts like
   a task development plan (features/tasks), wireframes/mockups (GUI design),
   statecharts/controller structure (design diagrams), and integration with
   REST-based Servers (API/JSON specifications).

3) To offer 'Tasks' as an intuitive and powerful agile software management
   tool to replace cumbersome task/issue tracking software.

4) To provide a superior GUI to manage SproutCore issues as it undegoes an
   explosive launch and maturation as a premier HTML5 framework.
   What better that an application built in SproutCore to manage its issues?

'Tasks' is under development - maturing into a tool to manage the development
of complex software.  I hope you will find 'Tasks' useful as you start your
journey with SproutCore.  Please send me your feedback or code contributions!

-Suvajit Gupta (suvajit_gupta@yahoo.com)


B. GETTING STARTED WITH 'TASKS'
================================================================================

There are several things you can do with 'Tasks' (but you will have to read
section C below for all of them!):

1) Deploy/use it as a tool (this will take about 20 minutes the first time).
   If you need to customize 'Tasks' (e.g., put in a custom logo), read section D.
   If you deploy locally or to your intranet, read sections E, F, and G.
   If you deploy to the cloud, read sections I or J.  
   Read section K for rebuilding/redeploying 'Tasks' on the cloud.

2) Use it to learn SproutCore.  Read sections E, F, and H.

3) Contribute to 'Tasks' development and testing.  Read sections M and N.


C. DOWNLOADING 'TASKS' CODE
================================================================================

On a Mac, you must have "Xcode" and "git" installed before using the steps below.

If you don't have Ruby 1.9 (check by typing "ruby -v"), install and use
"rvm" to get it...

bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )

Add the following line at the end of your ~/.bash_profile or ~/.profile
[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm"

rvm install 1.9.2
rvm use 1.9.2 --default

If you don't have SproutCore installed type...

sudo gem install sproutcore

Change to the directory where you would like to work on 'Tasks' and type...

git clone git://github.com/suvajitgupta/Tasks.git tasks
cd tasks/frameworks
git clone git://github.com/suvajitgupta/sproutcore.git
git clone git://github.com/FrozenCanuck/Ki.git ki
git clone git://github.com/etgryphon/sproutcore-ui.git scui
git clone git://github.com/etgryphon/sai.git
git clone git://github.com/etgryphon/sproutcore-uds.git scuds
cd ../

sudo gem install bundler
bundle install && bundle install --binstubs


D. CUSTOMIZING 'TASKS' CODE
================================================================================

'Tasks' has several customizable settings to suit your specific needs.
This is useful if you deploy 'Tasks' on your intranet or the cloud.
Search for "Customizable" within 'Tasks' code to see what you can modify.

1) One common scenario is to build 'Tasks' in "To Do" mode:

  - Set "softwareMode" to false in "apps/tasks/core.js"

2) Another popular scenario is to customize your "Installation Title/Logo":

  - Add your logo to the "apps/tasks/english.lproj/default_theme/images" folder
  - Modify "apps/tasks/core.js" to specify if it is a "squareInstallationLogo"
  - Modify the Buildfile to customize the <InstallationTitle>
  - Modify "apps/tasks/english.lproj/main_page.js" to customize
    <InstallationTitle> and <installation-logo-filename>

Commit your changes so that you can later get code updates from git...

git add .
git commit -m "customization" .


E. RUNNING PERSEVERE SERVER
================================================================================

Persevere is a bundled server you can use to run 'Tasks' locally on your machine
or deploy on your intranet if your whole team needs to access it.  The Persevere
server doesn't enforce authorization - access control is only done in the GUI.
The Persevere server also doesn't email notifications at this time.

1) To start the Persevere server...

./scripts/server-start.sh

2) To stop the Persevere server...

./scripts/server-stop.sh


F. CREATING USERS IN PERSEVERE
================================================================================

After starting the Persevere server (see above), run a script to create the
first user (after which you can log into 'Tasks' and use the User Manager GUI):

./scripts/user-add.sh "System Admin" "SA" "Manager" localhost:8088
(enter/reenter password and remember it!)

./scripts/user-add.sh "Guest User" "guest" "Guest" localhost:8088
(press Enter twice to create a blank password)


G. ADMINISTERING PERSEVERE
================================================================================

Navigate to the following URL to directly manipulate Persevere data:

http://localhost:8088/tasks-server/explorer.html


H. LAUNCHING 'TASKS' GUI
================================================================================

1) Start the SproutCore server...

./bin/sc-server --port 4400

2) Navigate to the following URL...

http://localhost:4400/tasks

3) Enter "SA" in the dialog box and the password you set earlier and press Enter.
   The 'Tasks' GUI should come up.

4) Add your projects and tasks and have fun with 'Tasks'!
   To get some sample data to play with, you can click
   on the Import button and paste in the contents of the file
   "apps/tasks/tests/data/import_data.txt"


I. DEPLOYING 'TASKS' ON GAE MANUALLY
================================================================================

You can deploy 'Tasks' to the cloud using GAE.  The GAE server enforces the same
authorization as the GUI access control, making it a secure deployment to protect
the integrity and privacy of your data.  The GAE server also supports email
notifcations.

1) If you don't have a GAE account, sign up here:

http://code.google.com/appengine/

Click on the "Download" link for the App Engine SDK and then click on
"Google App Engine SDK for Python" and install it on your computer.

2) Sign in to GAE and create an application by browsing to:

http://appengine.google.com/

Login to your Google account and click "Create Application".

The first time, you will be prompted to enter your mobile number to receive a
registration code. From the text message, copy the registation code into the prompt.

Enter a unique <application-identifier> and application title and press
"Create Application" button at the bottom.

3) Get the Tasks-GAE server code:

cd ../
git clone git://github.com/joshholt/SproutCoreTasks-AppEngineBackend.git <application-identifier>

4) Build 'Tasks' GUI for deployment (this may take a few minutes...)

cd ../tasks
./bin/sc-build -rc --build=build --languages=en

After sc-build finishes, copy tasks production build for deployment on GAE:
(for this "cp" command make sure there is no slash after "static" which you may
get if you tab for filename completion)

cp -r tmp/build/static ../<application-identifier>

5) Run GoogleAppEngineLauncher to add your new application:

From "File" menu, choose "Add Existing Application..."
Click on "Browse" and find/select the <application-identifier> folder,
press "Choose" and then "Add"

6) Configure/customize GAE application before deployment:

cd ../<application-identifier>
Open "app.yaml" and replace <application-identifier> on first line

Open "notification.py" and replace "suvajit.gupta@eloqua.com" with the email you use to login to GAE

You can optionally customize "only_allow_manager_login" in "main.py" so that only
"Manager" users can log in - this is useful in securing your personal data.
	
Commit your changes so that you can later get code updates from git...

git add .
git commit -m "customization" .

7) Deploy 'Tasks' to the cloud by pressing "Deploy" from GoogleAppEngineLauncher:
   (this can take a few minutes...wait until it says "finished with exit code 0")

Browse to http://<application-identifier>.appspot.com to launch your new 'Tasks'

8) Add yourself as a user via the same approach as what is outlined in section F:

cd ../tasks
./scripts/user-add.sh "<Full Name>" "<Login Name>" "Manager" <application-identifier>.appspot.com
(enter/reenter password and remember it!)


J. DEPLOYING 'TASKS' ON GAE USING SCRIPT
================================================================================

1) Run the following command from inside 'Tasks' root directory
	> python tasks.py setup <application-identifier> build
	
2) Then follow steps 8 & 9 below in the GOOGLE APP ENGINE DEPLOYMENT


K. REBUILDING/REDEPLOYING 'TASKS' ON GAE
================================================================================

1) If you made any mistakes while building or deploying or need to make additional
changes to Tasks later, follow these steps:

cd ../tasks
rm -rf tmp

From section I, repeat step 4 and then 7

2) Periodically, you can fetch code updates from git to get new features and fixes.
Make sure any changes you made are first committed (see section D).
To get code updates while you are in the "tasks" directory:

git fetch origin
git rebase origin/master

You can also get GAE Server updates with the same commands from your
"<application-identifier>" folder.

Repeat step 1.


L. ADMINISTERING GAE
================================================================================

If you need to add/update/delete GAE applications run GoogleAppEngineLauncher
and press the "Dashboard" button.  Login to your Google account and click on
"My Applications" to get access to your applications.

To modify any data directly in the database click on "Datastore Viewer"
button under the "Data" group.  Choose the type of 'Tasks' records to view/edit.

Since 'Tasks' soft-deletes data you should periodically cleanup these records
on the GAE Server.  This is an advanced topic that is detailed in the code.


M. 'TASKS' ARTIFACTS
================================================================================

'Tasks' ships with several artifacts in the "documents" folder to help you
understand its design/plans:

1) "plans/TasksDevelopmentPlan.txt" shows the work breakdown and assignments
   (see last sentence of Step 8).

2) "GUI/TasksWireframe.png" shows the initial GUI design with callouts explaining
   the key functionality.

3) "GUI/TasksMockup*.png" shows the visual design concepts used to style 'Tasks'.

4) "design/TasksStatecharts.pdf" shows the states/transitions within the GUI.

5) "design/TasksControllers.pdf" shows how the various controllers are wired
   and how the views relate to them (implementing the root controller pattern).

6) "API/TasksAPI.xml" drag this file into your browser - the files in the
   "include" folder render this specification in a nice format for you to
   understand the REST API endpoints.

7) "API/TasksJSON.xml" documents the model object structure for what is sent to
   the server via REST calls.

8) "API/TasksFileFormat.txt" Shows the simple/intuitive syntax for importing data
   into and exporting data from 'Tasks'.  In fact, the TasksPlan.txt is itself
   written in this format and can be imported into 'Tasks'!


N. AUTOMATED TESTING OF 'TASKS' WITH LEBOWSKI
================================================================================

Lebowski is used to test 'Tasks' end-to-end (GUI<=>API/Server/DB).
First get the latest Lebowski...

sudo gem install lebowski

1) From another terminal window, run the Lebowski server:

lebowski-start-server

2) In another terminal window, from the "tasks/spec" folder, run Lebowski scripts:

lebowski-spec -f n main.rb

To re-run the scripts:
  - stop Lebowski server by pressing "Control-C"
  - repeat steps 1) and 2)


APPENDIX. 'TASKS' ATTRIBUTIONS
================================================================================

The filter on/off icons:
Diagona Icons
Copyright (C) 2007 Yusuke Kamiyamane. All rights reserved.
The icons are licensed under a Creative Commons Attribution 3.0 license.

The color indicators on the filter icon, as well as numerous other icons in 'Tasks':
Silk icon set 1.3
Mark James - http://www.famfamfam.com/lab/icons/silk/