

# Introduction

> This document covers detailed explanation of how we are going to implement Task-based work flow for running GHOP. A more detailed discussion containing requirements for implementing GHOP features in Melange is documented [here](http://code.google.com/p/soc/wiki/GHOP).


# Details

The entire work flow is divided into 5 roles, namely
  * Program Admin (PA/LH)
  * Organization Admin (OA)
  * Mentor
  * Student
  * Public - This role indicates a general user who has not registered with Melange to access specific views.

## Program Admin
  * Program Creation View - Already exists (same as GSoC).
  * Program Configuration View - Will have options to create new task types and new task states, specify lower age limit, number of winners and runner-ups, prize to be given for winner and runner-ups, timeline for the program and the maximum number of tasks that the student can work simultaneously during the program. None of these fields will be mandatory, so PA can fill it up whenever she has the relevant details.
  * Organization Applications Review View - (Same as GSoC)
  * Task Quota Limits - PA will be able to assign tasks-limit quotas to Organizations and will be able tune it whenever required. (GSoC slot allocation interfaces can be re-used?)

## Organization Admin
  * Add/Edit/Delete New Tasks View - Fields to provide task title, task description are provided. OA will be able to select one of the task types and task states which are defined by PA. There will be a text box to provide arbitrary tags, a field to set the time required to complete the the task(which takes values in hours). A comment box will be provided. The view will also have an option to set the difficulty level(Open question: Should difficulty level be a text box or be selected from a drop down menu containing pre-defined difficulty levels. If it is latter, where and to whom should we provide the option of defining the difficulty levels?). A field to assign mentors to the task will also be provided. If a student has claimed the task, in the edit View there will be an option to either accept or reject the request. Will have an optional button to extend the deadline by 24 hrs for the student who have not completed the work.
  * Tasks Approval View - If mentors add/delete tasks, all such actions will be listed in this view. Bulk Acceptance option will be provided as a check box for each task listed and approve all the selected tasks.
  * List of "Tasks with Action Needed" View - This view lists all the tasks that are requested by students to claim, list of tasks for which students have submitted their work. Clicking upon the corresponding task will take him to the edit view of that task.
  * (NTH) Bulk Add Tasks View - This view will give the user the ability to upload a CSV file containing the set of tasks to be uploaded in bulk.

**Assign mentors on the Edit task page should be made mandatory form field for publishing the task.**

## Mentor
  * Add New Tasks View - All the options will be same as the one provided for OA, but to add or delete tasks OA should approve the action(Should OAs approve Editing too?). The person who creates the task will be assigned as the mentor automatically. The URL used for this will be the same as the one used by OA.
  * List "Tasks Added by Me" View - Mentors will be able to view the list of tasks added by himself.
  * Edit Tasks View - Mentors will be able edit the tasks without approval from OA(see question below). URL is same as the one used for OA.

### Life time of a task
  1. Mentor John creates 3 tasks one after the other.
  1. He is automatically assigned as mentor for all 3 tasks.
  1. Waits for those tasks to be approved by the OA.
  1. While waiting for the OA to approve the tasks he realizes that task #3 is not correct, so he deletes it and he needs not to get approval for deleting the task at this stage.
  1. OA approves other 2 tasks, reassigns Richard as a mentor for the task #2 but leaves task #1 as it is.
  1. Mentor John can edit both tasks #1 and #2 even though he is not the mentor of task #2 to change the task state, type, tags, time limit and difficulty including editing the task description content. (**Note:** mentors can edit the tasks irrespective of who created it or who is the mentor assigned)
  1. Student David requests to claim the task #1 and student Paul requests to claim task #2.
  1. Knowing Paul is a spammer, John rejects the request, but approves David's request, changes the task state to "claimed".
  1. Now student Lisa requests to claim task #2 and Richard approves her request and changes the task state to "claimed".
  1. In the due course of progress, both mentors and students discuss about the task. David submits his work and checks, "NeedsReview". David and John discussed that David requires more time than it was originally specified for the task. So John sets the task state to "NeedsWork" and he resets the deadline to count from now. (**Note**: Deadline can be extended only when the task is being set to NeedsWork state)
  1. Lisa on the other hand doesn't submit her work on time. So she automaticaly receives a 24 hour extension of the deadline together with a reminder email.Lisa neither replies not submits her work in next 24 hrs, so the task is automagically re-opened.
  1. David submits his work and John is happy about it and sets the task state to "closed".
  1. David now requests to claim task #2 and Richard accepts it and assigns task state to "assigned".
  1. David and Richard realize that it is difficult to complete the task at all by GHOP students.
  1. Richard sets the task state to reopened and then deletes the task even though he did not create it. He doesn't require permission from Org Admin at this stage. David can claim another task now. (**Note:** To delete a task, the task should not be claimed or assigned to any student)

## Student
  * Task Description View - All the fields set by OA/Mentors will be displayed. A button to "request to claim" the task will be provided. If the student has already requested to claim this task, we replace the "I request this task" button by "I withdraw".
  * In-progress Task View - The contents are exactly the same as the previous view, including "I withdraw" button, with few additions. Firsly it is provided just to give easy access to the task the student is working on. He will be able to submit his work here as a file(Should we allow upload of single file only so student can archive if he has multiple files and upload or should we allow upload multiple files, GMail-attachment style?). It is not yet confirmed that work submissions will be accepted in Melange. It depends on what LH tells us after discussing with the legal team. An additional text box will be provided to specify links to the work done for this task. After the task is completed, the student should be able to change the task state to "NeedReview" which will trigger a notification.
  * Completed Tasks View - Provides a list of all the tasks completed by the particular student.

Additional common items
  * All the above views will have Star this Task button.
  * Comments will have an integrated, "comment and claim" button.

### Life time of a task

  1. Student David goes to the view that lists all tasks.
  1. Filters them first on "Newly Added tasks" and then filters this list on "Organization Melange" (any order is possible)
  1. He then filters the tasks that have the type "Documentation" and Difficulty level "Medium"
  1. He sees a task titled "Document GHOP progress bar related features in Melange" interesting to him. So he clicks on it in the list and enters the task description page.
  1. He reads the description and he is interested in requesting to claim it, but there is no button to claim the task. Instead at that place, the page says "This task has been requested by Lisa".
  1. So he goes back to his filtered list and sees the task titled, "Document GHOP Prize allocation features in Melange". He reads the description, now he sees a button "I request to claim this task" and clicks on it.
  1. David is very eager to win prizes so he doesn't want to waste his time, so he goes back to the unfiltered list of tasks, filters it by "New Task" and then by "Organization PSF" and then the task type by "code". He sees a task titled, "Re-organize module FOO and BAR". He reads the description and clicks on the button "I request to claim this task".
  1. The system raises an error informing David that this program only allows him to work on one tasks at a time.
  1. He feels that this task is more interesting to him than the one he has already requested. The previous task is not assigned still. So he goes back to that task page and clicks on "I withdraw".
  1. He returns to the PSF task and requests to claim this task. After a few minutes he's succesfully claimed this task.
  1. At the same time Lisa, who is working on some other task feels it is difficult for her to complete in the given time limit after submitting her interim work her mentor decides to give here additional time. Even after the extended time limit she doesn't submit more work and the task is automagically "re-opened".
  1. David completes his task and uploads the diff files on task description page (Note this field is available only because David was assigned this task, no one else would get the field to upload the files). He also adds Mailing List discussions as additional references to his work, marks the "Needs Review" check box and hits submit.
  1. David goes to the tasks list, selects another task and tries to request that task, but he still gets the error telling he is supposed to work on only one task at a time, since his previous task is not yet closed.
  1. Mentor John now looks at David's work, discusses with him and they decide it needs some more work. John sets the task state to "Needs More Work" and gives David an additional 48h.
  1. David works some more on his task, uploads the work, checks "Needs Review" again and submits it.
  1. John is happy this time and he sets the task state to closed.


In all the above 3 views, student will be able to add comments to that specific task.

## Public
  * Task Description View - All the fields mentioned above for student will be visible, but they will be read only. However an option to post comments will be provided.

## Actions common to multiple roles
  * List Tasks View - This view will be available to all roles. By default all the tasks will be listed. Following filters will be provided to narrow down on the list of tasks. Filter by
    1. Organization.
    1. Difficulty level.
    1. Type of Task.
    1. State of Task.
    1. Time required for completing it.
    1. Newly Added.
    1. Students (LH should get permission from legal team).
> Each task listed will be linked to the specific task description page setup by OA/Mentors.
  * All roles will have an option to subscribe to a specific task.
  * All the roles except Public role will have a view for signing up.

## Automagic
  * Whenever something changes on the task page, every one subscribed to the task should get a notification.
  * Student will be allowed to work on at most the number of tasks specified by PA in the program configuration. If he ever tries to request a second task while he has requested another task, the system will raise an error. The student will be allowed to request the next task only when the mentor/OA for that task sets the tasks state to "Closed".
  * Once the student requests a task, that task will be locked down, so there will be no button for subsequent students to claim it, until it is reopened.
  * (NTH) Once the task is assigned to the student, the student and the mentor should get remainders at specific intervals about the deadline.
  * In the student sign up page, Birth Date will be a mandatory field and the provided Birthday is checked with the lower age limit provided by PA in Program Configuration page, if it violates the student will not be allowed to sign up.
  * Task States, Difficulty level and types appear as drop down in Task Creation or edit pages(The select values are read from Program Model and stored in the Task Model)

# What should Side bar contain for each roles?

## Program Admin


## Org Admin


## Mentor


## Student


## Public


# Model Design

Reference: [Melange Module Architecture](http://code.google.com/p/soc/wiki/MelangeModuleArchitecture)

**Legend**
  1. The heading specifies the model name and the bulleted items specify the properties to be stored in the model.
  1. Reference properties in the model are italicized.

## Task
We will be storing a reference to User property which is mandatory and an optional reference to a Student property. So when a particular student claims his first task we just attach the User property to it. However once he completes the task, before it is set to be completed we will enforce to fill in his student profile so we don't lose track of it. This also helps us to show if the task is taken up by a new student.

  * _user_ - **ReferenceProperty(User)**
  * _student_ - **ReferenceProperty(Student)**
  * _organization_ - **ReferenceProperty(Organization)**
  * _mentors_ - **ListProperty(type-db.key,...)** (List of mentors assigned for this task.
  * title - **StringProperty**
  * description - **TextProperty**
  * difficulty - **StringProperty** (Pre-defined by Program Administrator in the Program Configuration Page)
  * state - **StringProperty**
    * Each task should have one of the following task statuses:
      * Unapproved: If task is created by mentor, this is the automatically assigned state,
      * Unpublished: This task is not published yet,
      * Open: This task has not yet been claimed,
      * Reopened: This task has been claimed but never finished and has been reopened,
      * ClaimRequested: This task has been requested to be claimed by a student,
      * Claimed: This task has been claimed and someone is working on it,
      * ActionNeeded: Work on this task must be submitted for review within 24 hours,
      * Closed: Work on this task has been successfully completed.
      * AwaitingRegistration: Student has completed work on this task, but needs to complete student registration before this task is closed.
    * additional states need polishing/review with legal
      * NeedsWork: This task is nearly there, but a bit more must be accomplished. (following mentor review)
      * NeedsReview: Student has submitted work for this task and it should be reviewed.
  * type - **StringListProperty**
  * was\_reopned - **BooleanProperty** (Stores if task was reopened. Helpful when task is reclaimed
  * time\_to\_complete - **IntegerProperty** (Time allowed for completing the task (in hours) from the moment that this task has been assigned to a student.)
  * deadline - **DateTimeProperty** (Once the project is set to be "Claimed" we calculate and store this property in the entity)
  * tags - **StringListProperty** (Pending on conclusion on tags)
  * created\_by - **ReferenceProperty(Role)**
  * edited\_by - **ReferenceProperty(Role)** (Changes only when OA/Mentor change title/description, difficulty, type, time-to-complete only)
  * created\_on - **DateTimeProperty**
  * edited\_on - **DateTimeProperty**
  * history - **TextProperty**

Task history is stored as JSON string. At the top level it is a dictionary with key being the timestamp and value being another dictionay containing the changes. `_`onCreate() it stores the snapshot of the entire task as it was when it was created with all properties in it. Upon each change a new dictionary item will be created with key being timestamp when the Task entity change was triggered. The value for this item will be a dictionary with key fields being the name of the property that changed and its value being the changed value.

Sample JSON Object:
{
> "1242938868": {
> > "user": "madhusudancs"
> > "student": "madhu"
> > "organization": "melange"
> > "mentors": ["lennard", "pawel"]
> > "title": "GHOP test task"
> > "description": "This is an awesome task. Work on it and win a prize!"
> > "difficulty": "easy"
> > "state": "ToBeApproved"
> > "type": "Documentation"
> > "time\_to\_complete": 48
> > "deadline":
> > "created\_by": "paul"
> > "edited\_by": "paul"
> > "created\_on": 1242938868
> > "edited\_on": 1242938868
> > }
> > "1242939222": {
> > > "state": "Open"

> > }
}

The following models are shared models with GSoC with different OOP. Look at Module Architecture.
## Organization

  * task\_quota\_limit - **IntegerProperty**

## Student
  * school\_type - **StringProperty** (It can be either High School or University, provided as a drop down)
  * major - **StringProperty**
  * degree - **StringProperty** (These 2 property fields appear on student sign up page if the program chosen is University type)
  * grade - **StringProperty** (This is chosen if program type is High School. I plan to use AJAX for this kind of form generation)


## Program
  * student\_min\_age - **DateTimeProperty** (We are storing the the latest birth date above which a student cannot participate. For example if the contest rule says, "must be 13 years or above on November 1, 2009". We store this is as November 1, 1996 in DateTimeProperty format)
  * number\_of\_simultaneous\_tasks - **IntegerProperty**  (Configurable in Program Configuration page by Program Admin. For GHOP it is 1, the number of tasks students can work on simultaneously)
  * number\_of\_prize\_winners - **IntegerProperty**
  * number\_of\_runner\_ups - **IntegerProperty**
  * task\_difficulties - **StringListProperty**
  * task\_states - **StringListProperty**
  * task\_types - **StringListProperty** (All the above properties are configurable in program configuration page)

## Mentor
  * **No changes seem to be necessary**

## OrgAdmin
  * **No changes seem to be necessary**

## Timeline
  * task\_claim\_deadline - **DateTimeProperty**
  * stop\_all\_work - **DateTimeProperty**
  * winner\_selection\_start - **DateTimeProperty**
  * winner\_selection\_end - **DateTimeProperty**
  * winner\_announcement - **DateTimeProperty**
Reference: [GHOP 2007-08 FAQ](http://code.google.com/intl/nl/opensource/ghop/2007-8/faqs.html#tlq1)

## PrizePerOrg

> This model holds the students who have won the prizes for a particular program instance for each organization.
  * _program_ - **ReferenceProperty(Program)**
  * _organization_ - **ReferenceProperty(Organization)**
  * prize\_winners - **ListProperty(type=db.key, ...)** This holds **ordered** keys for Student entities as given by an Organization for winning prizes.
  * runner\_ups -ListProperty(type=db.key) This holds keys for Student entities that are considered runner\_ups, a key **cannot** be found in both the prize\_winners and runner\_ups property.

## WorkSubmission (To Be Decided)
  * _task_ - **ReferenceProperty(Task)**
  * _user_ - **ReferenceProperty(User)**
  * _program_ - **ReferenceProperty(Program)**
  * _org_ - **ReferenceProperty(Organization)**
  * file - **BlobProperty** (Holds the uploaded file. Has 1MiB per file App Engine limitation)
  * additional\_work - **StringProperty** (Holds the URLs or any other kind of pointers to external work)
  * submitted\_on - **DateTimeProperty**

## Comment
  * change\_in\_task - **StringProperty** (Holds the human readable string that should be shown for the comment when something in the task changes. code.google.com issue tracker style)

# Task States

## Description of how state transitions
_Describes how the **state** property in the Task model works._

Note: User will not have direct control on the value of the states. The logic code will take care of all the state transitions that are allowed to occur.
  * When a mentor creates a task, the state is initialized to **Unapproved**. If the task is created by an Org Admin it is automatically initialized to **Unpublished** state. The was`_`reopened property will be set to **False** by default.
  * The Org Admin can bulk choose tasks for publishing.(will be given list of tasks in Unpublished state with check boxes. Can check the tasks and click on Publish button). The tasks state changes to **Open**. Org Admins will be also be given button to Approve and Publish at once.
  * When a student requests to claim a task, the system checks if there exists a Student entity for this user. If it exists we need to worry about signing up the student. If it doesn't exist then we need to check if student has already completed one task successfully. If yes, the system forces him to sign up and returns back to this page and the state changes to **claimrequested** in either cases.  The amount of tasks that the Student has requested to claim or has been assigned to will be checked with the amount of simultaneously allowed tasks in the program settings.
  * Org Admin/Mentor can either accept the request in which case the task state is set to **Claimed** or reject the request in which case state is changed to back to **Open** since the was`_`reopened property is **False**. If was`_`reopened is **True** the state changes back to **Reopened**.
  * If a student withdraws the claim request before it was assigned to him the state changes to either **Open** or **Reopened** depending on the value of was`_`reopened.
  * If the student withdraws from the task after it was assigned to him the state is changed to **Reopened** irrespective of the value of was`_`reopened and was`_`reopened is set to **True**
  * The student can submit his work using the Additional info text box (or upload the files - yet to be decided). check the _Request to review the work_ option in which case the task state changes to **NeedsReview**. They will be able to edit their submissions, in case of any mistakes.
  * Now the Mentor is given a Drop Down with options to
    1. Fail the student, in which case the state changes to **Reopened**
    1. Pass the student, in which case the state changes to **AwaitingRegistration** if this is first task the student has completed successfully. Otherwise state changes to **Closed**.
    1. Work is not sufficient/satisfactory, in which case a text box appears to allow Mentor to set the extended deadline in hours and upon that changes the state to **NeedsWork**.
> > A comment box is also provided to mentor to explain his actions.
  * If the deadline is passed and the student doesn't submit any work the state automatically changes to **Reopened**.
  * If the task is in the Claimed state and the deadline has passed, the state will change to **ActionNeeded** and the deadline will be extended by 24 hours. This can only happen in the Claimed state.


## Visualizing the states of a Task
![http://img230.imageshack.us/img230/1641/taskstatemachine.png](http://img230.imageshack.us/img230/1641/taskstatemachine.png)
![http://img15.imageshack.us/img15/5099/taskclaimstatemachine.png](http://img15.imageshack.us/img15/5099/taskclaimstatemachine.png)
![http://img231.imageshack.us/img231/5739/taskclosestatemachine.png](http://img231.imageshack.us/img231/5739/taskclosestatemachine.png)
![http://img219.imageshack.us/img219/8198/taskwithdrawalstatemach.png](http://img219.imageshack.us/img219/8198/taskwithdrawalstatemach.png)

# User Interface
This section contains the UI Design of the GHOP specific functionalities in detail.
## Task Page for claimed student
Description of how the Task page looks for a student who has claimed it:
  * The page starts with read-only items like Task title, description, type, difficulty level among other things.
  * Then it will have an "Additional Info" text box for providing links to external work.
  * Below this will be a text box for providing additional information about the work in form of comments.
  * Below is a check box to request for reviewing the work by the mentor to be checked by the student, followed by a Push button "Submit"
  * This is followed by a collapsible list of submitted work along with the student who submitted it and date of submission and its relevant comments sorted in the chronological order.
  * Finally at the bottom most of the page is the list of comments for this task sorted in the chronological order. The comment content of the work submission will also be copied to this comments list and a description of what changed for the task will also be shown.


# Schedule

  1. Community Bonding - ( Current - May 22nd )
> > Refine requirements. Document design decisions and implementation. Write unit tests(ATM I am writing tests for Organization and Program logic and views).


> 2. Coding Phase I (May 22th – June 2nd )
> > Implement all the models.


> 3. Coding Phase II (June 3rd – June 10th )
> > Implement
    * Program Admin roles's views: Program Configuration View, Task Quota Limits
    * Organization Admin: Add/Edit/Delete New Tasks View, Tasks Approval View, List of "Tasks with Action Needed" View.
    * Mentor: Add New Tasks View, List "Tasks Added by Me" View, Edit Tasks View
    * Notification System and options to (un)subscribe to tasks.

**Breaking for 8 days - June 11th to June 18th due to bachelor degree end sem examination.**

> 3a. Resuming Coding phase II (June 19th - June 29th)

> 4. Testing Phase I (Will postpone and merge it with Test Phase II or will plans as required. )
> > Write Unit tests for the above implemented views and logic.


> 5. Coding Phase III (June 30th – July 24th )
> > Implement
    * Student: Task Description View, In-progress Task View, Completed Tasks View.
    * Public: Task Description View.
    * Common Views: List Tasks View
    * Automagic:
      * Enforcing student to work on atmost N number of tasks at a time.
      * Enforcing a task to be claimed by only one student.
      * Check for minimum age limit on the student sign up page.
    * All the filters will be implemented.


> 6. Testing Phase II (July 25th – July 31st )
> > Writing unit tests for all the above views and logic.


> 7. Requesting for community wide Reviews, testing and evaluation
> > (August 1st – August 3rd )
> > > Final phase of testing of the overall project, obtaining and
> > > consolidating the results and evaluation of the results.
> > > Requesting community to help me in final testing and closely
> > > working with testers.


> 8. Scrubbing Code, Wrap-Up, Documentation
> > (August 4th – August 10th )
> > > Fixing major and minor bugs if any and merging the project
> > > with the Melange hg repository. Writing User and Developer
> > > documentations and finalization.

## Features Available at Midterm Evaluation

  * Notification e-mails for change in status of tasks.  Options on what to be notified about.  Might entail many round-trips to server if changing notification options on many tasks.
  * Some GHOP specific logic, such as student may select max one task at a time.
  * More flexible timeline.py.  Might be done by copying the basic one and changing it a bit for GHOP, so it might not actually be more flexible, just a different variant.

**JC** asks if any of the following features will be present at the mid term.  Madhusudan's answers that "They are not planned for the mid term.  They are nice to haves."

  * Preferences page for students so they can set notification options.
  * Tickable list, usable for subscribing/unsubscribing to notifications (with one round trip to server) and potentially useful elsewhere.
  * Bulk accept of tasks (this is not import from CSV, rather it is selecting which tasks to move from ready to visible status).  This would use the tickable list.
  * Incorporation of Taggable.py into Melange.
  * File upload support
  * Calendar integration
  * Atom feeds
  * GHOP+Stats (i.e. some work to show that stats can work on GHOP data)
  * GHOP+Surveys (probably no integration/dependencies here, but it's mentioned here as surveys were mentioned in GHOP plans.)

Tickable lists, tags and preferences page are all features which have multiple uses in Melange.  They fit in very naturally in GHOP, but they are also relevant to the StatisticsModule.  It now looks likely (unless GHOP plans change) that other developers will claim at least Tags and probably tickable list too, since GHOP is not planning to have these for the mid term.

# Questions
  * Lennie suggested that for viewing individual task description, we will have a common URL to all the roles, i.e students/mentors/OA and then display the forms with specific actions they want to do and the edit page allows to edit the contents of the task. However my initial thought was to have a common Individual Task Description/Edit View for Mentors/OA where they can either edit the contents of the task as well perform actions like changing states, adding deadlines and relevant things and have a different URL for students to view the task description, request to claim it and upload the work after the work is complete. This is an open question. If you have something else other than these 2 please add them.


&lt;Pawel&gt;

Common url is fine with me the content of the page will change based on user Role so either way is fine.

&lt;/Pawel&gt;


  * If the above properties of winner and runner ups are acceptable, I planned to store the runner ups as a list of **ReferenceProperty** s to Student model, which conceptually boils down to a PrizePerOrg 1:N Student relation and following the rules of Database design this needs to be stored as a reference to PrizePerOrg Model in the Student model. And this kind of design just for being conceptually correct is not making sense to me. I am a bit confused as to what to do here. Can any one suggest me a way out here please?


&lt;Lennard&gt;

The relation could be N:N if a Student is allowed to win multiple prizes. This seperation is also good for clarity since it is easier to see all winners for one program this way.

&lt;/Lennard&gt;


  * Is a Student allowed to win multiple prizes or be runner-ups for multiple Organizations? Do we want to have a program option checkbox which dissallows something like this, or perhaps two IntegerProperties so we can say "Max allowed prizes per Student" and "Max allowed runner-up prizes per Student"?

  * Should we allow file uploads for work submissions? Waiting for LH for an answer.