#summary Starter Manual for using GCI module.
#labels Importance-Useful,Phase-QA,Contents-Draft

<wiki:toc max_depth="3" />

= Introduction =

  This document covers detailed explanation of how to use the Task-based work flow, GCI module of Melange. These features are available for you to try out at the demo instance running at [http://melange-madhusudancs.appspot.com http://melange-madhusudancs.appspot.com]. It will soon be made available through [http://melange-demo.appspot.com http://melange-demo.appspot.com]


= Details =

  This document is exclusively written for users of the GCI module of Melange, and is in no way a developer manual. If any of you are willing to contribute to GCI module in particular, please ping any one of the developers on our IRC channel: #melange @ irc.freenode.net or on our developer mailing list.

  The following document is divided into 5 separate sections, one for each role of Melange.

== Program Admin(PA) ==

  A Program Admin(PA henceforth) is one who creates and manages a GCI Program. He/She has all the rights of an Org Admin and a Mentor.

  * Create/Edit Program Admin profile: TBD
  * Create the GCI program: TBD
  * Edit the GCI Program: The PA will have a link on the sidebar under the <Program Name> menu to edit the Program profile. The following are the list of things that PA can set from the Program profile page:
    * Org Admin, Mentor, Student Agreement document link ids.
    * Home page link id
    * Minimum age of the participating student to be enforced and the date as of which this requirement must be met.
    * She can also set the maximum number of tasks that a student can claim simultaneously (1 for GCI).
    * She can also set Winners and Runners-up per organization.

=== Timeline ===

A PA must set:

  * All the program specific timeline in the edit program timeline link available from the sidebar
  * Org App and all other survey timeline in the *Survey Create/Edit page*. Note Org Admins will not be able to apply as organizations just by setting the Org signup start and end dates in timeline but also be made sure that it is set in the Org App survey.


== Organization Admin (OA) ==

  An Organization Admin (OA henceforth) is one who creates and manages an Organization under the GCI Program that PA has created. An OA does not have all the rights of a Mentor.  To perform any of the operations mentioned below i.e. to become an OA or to apply as an organization, the basic minimum requirement is to login to http://socghop.appsot.com with your Google account and create a profile by clicking on the "Create profile" link on the sidebar.

  The workflow to apply as a an organization and hence to become an OA
  * Once the Organization application period opens as per the program timeline a link titled "Apply to become an Organization" appears on the sidebar under the Programs menu's specific program for which Organization applications are open.
  * Login to http://socghop.appspot.com with the Google account you previously used to create your profile.
  * Click on the "Apply to become an Organization" link which is mentioned above.
  * Fill up the application and submit. *Note:* This form asks to specify a backup admin for the Organization and this is mandatory. You must specify the Link ID of another person who would like to be the backup admin for your Organization. And to specify the Link ID here in the backup admin field he/she should have already created a profile on http://socghop.appspot.com and that Link ID must be used.
  * Similarly you can submit applications to as many organizations as you would like to be OA of.
  * You can view the list of all the applications you have submitted by clicking on "List My Organization Applications" link under the same program.
  * The PA reviews your application and accepts or rejects it.
  * If your organization is accepted you will get a notification regarding the same.
    * To read the notification click on the "Notifications" link on the sidebar under the Users menu.
    * In the notification message click on the link that leads to a form where you can fill in your Organization profile.
    * Upon that you and the backup admin you had specified when you submitted the application will get a notification which contains the invitation to become an OA for the organization you registered the Organization profile with.
    * Clicking on that link will lead you(same for backup admin as well) to a page where you can accept/reject the invitation to become an OA for that Organization. Upon acceptance you are redirected to a form where you can fill in your OA profile.
    * On the sidebar you will now see a new submenu with your Organization name under the GCI Organizations menu which you can use to manage your Organization's work.
    * You may invite other users to become OAs or Mentors as you
  * However if your application was rejected no notification will be sent to you. But you can anyways find this out by clicking on the "List of participating organizations" link that appears on the sidebar under the same program once the accepted organizations are announced.


== Mentor ==

  A Mentor is one who mentors one or more student for accomplishing GCI Tasks.

  * Suggest a new task/Edit the task: The deadline for the task cannot exceed 30 days i.e in terms of hours it cannot exceed 720 hours.

== Student ==

  A student is one who can claim a task, work on it, submit his work and win prizes.

  * If student submits no work and the initial deadline passes, the deadline is automatically extended for another 24 hours. This shoots a mail to all the subscribers to the task notifying about the deadline extension. The task of the status is set to ActionNeeded. If the student fails to submit any work in that extended deadline of 24 hours also, the task is automatically re-opened. To learn how to subscribe to the task read the Rules of subscription below.

== Public ==

  Any user. Every such user is differentiated as a logged-in or non-logged-in user.


= General =
== Subscription ==

  * A user is subscribed to a GCI Task if the star button on the top of the Task public page preceding the task title is a glowing icon and is not subscribed otherwise.
  * He/She can subscribe to the task by clicking on the non-glowing star icon
  * And unsubscribe by clicking on the glowing icon.

Rules of the subscription game:
  * A mentor is automatically subscribed to the task the moment he suggests the task. Assigned mentors are *not* automatically subscribed to the task.
  * An Org Admin is automatically subscribed to the task the moment he creates the task.
  * A student is automatically subscribed to the task the moment he *Requests* to claim the task.
  * All other users must manually subscribe to the task by clicking on the star button.
  * No user is automatically unsubscribed from the task. All the users irrespective of a student who has claimed the task, Org Admin who created the task and mentor who suggested the task should unsubscribe from the task manually.


== Task ==

=== Prologue ===

  A task can be claimed by students and hence completed during the program. At any point in time, every task will be in one of the following states:
  # *Unapproved*
  # *Unpublished*
  # *Open*
  # *Reopened*
  # *ClaimRequested*
  # *Claimed*
  # *ActionNeeded*
  # *NeedsWork*
  # *NeedsReview*
  # *Closed*
  # *AwaitingRegistration*
  # *Invalid*
In addition every task will have mentor(s) assigned and time to complete value, in hours, associated with it.


=== A typical work flow ===

==== Setting up the scene ====

  # Either an Org Admin(OA) creates or the Mentor suggests a new tasks under the organiazation.
  # If the task was created by an OA it is automatically approved and hence in the *Unpublished* state
  # If the task was suggested by a Mentor it is in the *Unapproved* state
    # The OA can review the task and can either:
      # Approve the task which changes the task status to *Unpublished*
      # Or Publish the task directly which implicitly means the task is approved. This changes the status of the task *Open*. *Note to OAs*: It is not necessary to check the Approve box on the task edit form. If Publish box is checked it is implicitly assumed that the task is approved as well.  
  # If the OA thinks that the task is irrelevant or is a spam, he can delete the task which sets the task status to *Invalid*.
  # The OA can unpublish the task as long as the task is not claimed by any student i.e as long as it remains in the *Open* state. It is not possible to unpublish the task once the task status changes from *Open* to any of the claimed states. This is because the task never returns back to *Open* state.
  # An OA or the Mentor can edit the task as long as the task is not claimed by any student i.e. as long as it remains in one of the *Unapproved*, *Unpublished* or *Open* states. It is not possible to edit the task once the task status changes from *Open* state to any of the claimed states because of the same reason mentioned in the previous point.

==== Student enters ====

All the action on the task henceforth happens on the task public page. The following happens only after the Task is published, i.e. in the *Open* state.

  # A student submits the action "Request to claim" the task along with an optional comment and waits for approval. The task moves to *ClaimRequested* state.
  # This locks down both the task and the student to the task, meaning:
    # No other student can request to the claim the same task.
    # The student cannot request to claim another task. This also implies that if a student is already working on a task, he cannot request to claim any other task.
  # OA or any Mentor of the organization(irrespective of being a mentor of that task) can do one of the following with an optional comment:
    # Approve the request if it is valid and the student deserves it. The task moves to *Claimed* state.
    # Reject the request if the request is invalid, irrelevant or a spam. The task moves to *Reopened* state.

==== Student gets involved ====

  # If the claim request is accepted the deadline is set as specified by the time to complete field and the clock starts to tick. The student begins his/her work on the task.
  # If the student completes the work set out by the task before the deadline, he/she can submit the work by posting an comment along with the URL to the work. Note that one of the comment or the URL field is mandatory. The task changes the state to *NeedsReview*.
  # If the deadline passes with the student submitting no work, the deadline is automatically extended for another 24 hours. The task changes the state to *ActionNeeded* and the notification is sent to all the subscribers including the student if he has subscribed. For more about subscriptions read the section on subscriptions above.
  # If the student fails to submit the work even after the extended deadline, the task will be automatically re-opened and the task status will be set to *Reopened*.
  # If the student submits the work before this deadline passes, the same rule as the previous work submission rule applies.
  # One of the Mentors of the task reviews the submitted work. The mentor can take one of the following actions:
    # If the mentor is satisfied by the student's work he choses the action to "Close the task" along with an optional comment thereby marking the task as closed. The task moves to one of *AwaitingRegistration* or *Closed*. More about it below.
    # If the mentor is not satisfied with the work but thinks that it requires rework and student can do it, he/she will choose the action "Needs More Work" with an optional comment. At this juncture the mentor has the option to extend the deadline for the student. The task status moves to *NeedsWork*. The cycle goes back to the point where student has to submit his/her work again.
    # If the Mentor is completely unsatisfied with the student's work he/she will re-open the task. The task changes the state to *Reopened*. The new cycle with the same/another student requesting to claim the task begins.
  # The student can withdraw from the task at any point in this entire workflow after he requests to claim the task. In such a case the task returns to *Reopened* state.

==== Student exits ====

  # If the student's request to claim the task is rejected, the student can continue to request to claim the same task again or proceed to request to claim any other published task.
  # If the student successfully completes a task, the task is closed by the Mentor. If the student is not registered yet the task status is set to *AwaitingRegistration*.
  # In this situation the student should register with a student profile by clicking on the link "Register as a Student".
  # *Note* that we don't want the students to register until they successfully complete at least one task.
  # Also it is mandatory for the student to register once he completes the task, otherwise he cannot request to claim any more tasks and this task is not counted towards winner calculations.
  # Once the student registers, the task which he completed and was in *AwaitingRegistration* state is automatically set to *Closed* state and the student can continue requesting to claim other tasks towards his conquest to win Google Code In.

=== Epilogue ===
*Note:* Any registered user can post a comment on the task once the task is published.