Cai Jiaxiu - Project Portfolio

Overview

WatchOver is a gamified desktop task manager.

Summary of contributions

Major enhancement: added the achievements mechanism
- What it does: Keeps track of the achievement information of the user and displays it on the UI.
- Justification: This enhancement lays down the basic infrastructure for the gamification component of the gamified task manager. The achievement information provides users with incentive and motivation to complete the tasks. Daily and weekly achievement information also helps users keep track of their performances across time.
- Highlights: As the achievement information is updated per completion of task, the design of the mechanism needs to take into consideration of the undo/redo of complete commands. In depth analysis of alternative designs is required to support such integration to keep the achievement information consistent with the actual completion of tasks.
  The support for daily, weekly achievement information also requires the achievement mechanism to have a sense of time to update and reset such time based achievement fields.
  As the achievement information is presented on the GUI rather than via the CLI on achievement commands. Design considerations are also required to toggle back the achievement panel GUI display (e.g. from all-time to today) on undo/redo command.
  The whole mechanism requires extensive support and modification of all of the model, storage, logic and UI components of the existing software.
Code contributed: RepoSense.
Other contributions:
- Project management:
  - Managed release v1.4 on GitHub.
- Enhancements to existing features:
  - Added a status field to tasks to differentiate between in-progress, completed and overdue tasks.
  - Refactored the model component of address book to task manager.
- Documentation:
  - Overseeing UserGuide, formatted UserGuide and added in the unmodified features from the original software.
- Community:
  - PRs reviewed (with non-trivial review comments): #147 #130, #67, #141, #42.
  - Reported bugs and suggestions for other teams in the class: 240, 236, 228.
- Tools:
  - Integrate Netlify to team repo.

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Display achievements across a time period: `achievements`

Displays the cumulative achievements of a user across a specified time period on the GUI.
Such achievements include current level, xp earned and number of tasks completed across that time period.
Users automatically level up on gaining enough xp to reach the next level. The maximum level is capped at lvl.5.
Format: achievements TIME_SPAN, a valid TIME_SPAN may take the value of all-time, today, or this week.

+Example: achievements all-time
+Example: achievements today
+Example: achievements this week
-Example: achievements all time
-Example: achievements TODAY

Daily time-based achievement fields(today’s xp and number of tasks completed) are reset every day. Weekly time-based achievement fields(this week’s xp and number of tasks completed) are reset every week. The time range for all-time, today and this week’s achievements are shown as in the diagram.

Today and this week’s achievements assume users do not time travel.
Once a day/week is passed, its achievements cannot be retrieved again by achievements today/this week if the user ever comes back from the future.

If under the unlikely circumstances, the increased xp or number of tasks completed is expected to exceed 1000000000, these fields will no longer be updated.

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

Achievement mechanism

Structural Overview

The achievement mechanism is facilitated by AchievementRecord. TaskManager is added with an AchievementRecord on top of the original UniqueTaskList.

AchievementRecord stores the achievement information of the user internally. These information include the current Xp, current Level, total number of tasks completed across all time, as well as the xp earned and number of tasks completed by the user today and this week. To facilitate the tracking of the time-based achievements(namely xp earned and number of tasks completed by today and this week), AchievementRecord also stores the date and time when the time-based achievement fields should be reset.

AchievementRecord also contains a field displayOption that specifies which set of achievement information should be displayed on UI. The field is updated through the achievements all-time, achievements today or achievement this week commands.

The storage of the AchievementRecord is facilitated by XmlAdaptedAchievementRecord which is saved together with the list of XmlAdaptedTask in the SerializableTaskManager.

Integration of AchievementRecord in Model component:

Basic Mechanism

An updateTaskStatus method is implemented in ModelManager and exposed in the Model interface, this method is called in the execution of complete command. Upon completion of a task, the status of task is updated to COMPLETED, along with that, the AchievementRecord is also updated with the new xp. Current xp, number of tasks completed increases, current level is recalculated and updated to match current xp. As the time based achievement fields should be reset every day or week, checks are performed and the fields are reset if necessary. Xp earned and number of tasks completed today and this week is then increased as well.

An updateAchievementDisplayOption method is implemented in ModelManager and exposed in the Model interface, which is called in the execution of the achievements command. Before the displayOption field of the AchievementRecord is updated, checks are perform to reset the time based achievement fields if necessary as well to ensure that they are up to date. The displayOption is then updated, an AchievementsUpdatedEvent is posted to notify UI, who then display the set of achievement information as specified by user’s command.

Sequence diagram of the achievement mechanism:

Activity diagram of the update of daily time-based achievement fields(today’s xp, today’s number of tasks completed):

Event-driven Interaction with other components

The achievement mechanism follows the event-driven interaction of model component with Storage and UI components. When a task is marked as complete, both the UniqueTaskList and the AchievementRecord of the task manager is updated to reflect the new status of the task and the new achievement information. A TaskManagerChangedEvent is then posted to EventsCenter and handled by both Storage and UI components to save the changes and update the status bar.

On top of the TaskManagerChangedEvent, an AchievementsUpdatedEvent is posted by the Model component every time the AchievementRecord is update(on task completion or change of display option). This event is handled by the AchievementPanel UI component which then update the achievement information displayed.

Design Considerations

Aspect: Associations Among TaskManager,UniqueTaskList and AchievementRecord

Alternative 1 (current choice): Integrate AchievementRecord into TaskManager as an additional field besides the existing UniqueTaskList.
- Pros: Easy to implement, greater efficiency. As achievement information (eg. xp, level) changes always come together with task status changes, we can update both the UniqueTaskList and AchievementRecord then save the TaskManager only once. Undo/redo commands that revert the status tasks would revert the achievement information as well, matching between task status and corresponding achievements is guaranteed.
- Cons: TaskManager now has another reason of change, breaks Single Responsibility Principle.
Alternative 2: Implement AchievementRecord as another component outside of TaskManager and let them communicate through events.
- Pros: Follows Single Responsibility Principle. TaskManager handles only task operations, achievement information is handled by AchievementRecord independently.
- Cons: Logic is duplicated twice. For example, we would need to implement a VersionedAchievementRecord besides the current VersionedTaskManager to support undo/redo. A lot of overhead will result from the communication between TaskManager and AchievementRecord as well.

Aspect: Managing display option of AchievementRecord.

Alternative 1 (current choice): Use and additional field displayOption in AchievementRecord to keep track of display option. The field is updated when user uses the achievements all-time, achievements today or achievement this week commands to specify their choices.
- Pros: As the display option is saved inside the AchievementRecord of TaskManager, undo/redo of the achievements command is easily supported. AchievementPanel UI component can simple decide which set of achievements to display based on the current value of the displayOption field.
- Cons: AchievementRecord needs to save the display option besides the achievement information, this breaks the Single Responsibility Principle.
Alternative 2: Use AchievementPanel UI component to save and manage the update of display option.
- Pros: Follows Single Responsibility Principle. AchievementRecord handles only achievement information. Greater cohesion as the display of achievements is handled by the AchievementPanel UI component alone. AchievementPanel UI component does not need to rely on AchievementRecord model to decide which set of achievement information to display.
- Cons: AchievementPanel needs to save the states of the displayOption to support undo/redo. Undo/redo of the achievements command needs to be implemented and handled separately from all other commands, breaks abstraction.

Achievement Mechanism

Update of xp and number of tasks completed on task completion
1. Test case: complete 1
  Expected: Xp value on the achievement panel increases, tasks completed increases by 1. The actual amount of xp value awarded is determined by the current game mode and reported by complete command message.
2. Test case: complete l/tutorial
  Expected: Xp value on the achievement panel increases. The actual amount of xp value awarded is determined by the current game mode and reported by complete command message. Tasks completed increases by the number of tasks completed by the batch complete command (as specified in the complete command message).
Update of level on task completion
1. Prerequisites: change the specified fields in data/taskmanager.xml(or other storage path) to:
  <xp>499</xp>
  <level>lvl.1</level>
  <xpValueByDay>0</xpValueByDay>
  <xpValueByWeek>0</xpValueByWeek>
2. Test case: complete 1
  Expected: Xp value on the achievement panel increases, and level increases with xp(as the minimum xp of level 2 is 500). The actual amount of xp value awarded is determined by the current game mode and reported by complete command message. The level will always match the updated xp.
Update of achievement information on undo/redo of complete command.
1. Test case: complete 1 undo redo
  Expected: Achievement information updates as specified in the other test cases, changes back to original values on undo, and changes again to the updated values on redo.
Change of display option on achievement UI
1. Test case: achievements today
  Expected: Achievement panel shows "Daily achievements from [today’s date]:", current level, xp earned and number of tasks completed from the beginning of the day.
2. Test case: achievements this week
  Expected: Achievement panel shows "Weekly achievements from [date]:", current level, xp earned and number of tasks completed from the specified date.
3. Test case: achievements all-time
  Expected: Achievement panel shows "All-time achievements:", current level, xp earned and number of tasks completed across all time.
4. Test case: achievements all-time achievements today undo redo
  Expected: Achievement panel shows all-time achievement information followed by today’s achievement information. On undo, it shows all-time achievement information again and on redo, it shows back today’s achievement information.
Reset of time-based achievement fields
1. Prerequisites:
  1. change the specified fields in data/taskmanager.xml(or other storage path) to:
    <xp>400</xp>
    <level>lvl.1</level>
    <numTaskCompleted>14</numTaskCompleted>
    <nextDayBreakPoint>dd-mm-yy 0000</nextDayBreakPoint>(where dd-mm-yy is tomorrow’s date)
    <xpValueByDay>200</xpValueByDay>
    <numTaskCompletedByDay>5</numTaskCompletedByDay>
    <nextWeekBreakPoint>dd-mm-yy 0000</nextWeekBreakPoint>(where dd-mm-yy is today’s date + 7 days)
    <xpValueByWeek>300</xpValueByWeek>
    <numTaskCompletedByWeek>12</numTaskCompletedByWeek>
2. Test case:
  1. achievements today
  2. set the system time of the testing computer to be tomorrow(one day after today)
  3. achievements today
    Expected: Before system time change, achievements today shows "Daily achievements from [today’s date]:", today’s xp to be 200, tasks completed to be 5. After system time change, achievements today shows "Daily achievements from [tomorrow’s date]:", this day’s xp to be 0, tasks completed to be 0. All-time xp value remains 400, tasks completed remains 14. This week’s xp value remains 300, tasks completed remains 12.
3. Test case:
  1. achievements this week
  2. set the system time of the testing computer to be next week(7 days after today)
  3. achievements this week
  4. achievements today
    Expected: Before system time change, achievements this week shows "Weekly achievements from [today’s date]:", this week’s xp to be 300, tasks completed to be 12. After system time change, achievements this week shows "Weekly achievements from [next week’s date]:", this week’s xp to be 0, tasks completed to be 0. Now, achievements today shows "Daily achievements from [next week’s date]:", this day’s xp to be 0, tasks completed to be 0.
Detection of invalid/corrupted achievement information from storage

change the specified fields in data/taskmanager.xml(or other storage path) to:
1. Test case: <displayOption>5</displayOption> (invalid display option)
2. Test case: <xp>59</xp> <level>lvl.2</level> (non-matching xp value and level)
3. Test case: <xp>559</xp> <xpValueByDay>90</xpValueByDay> <xpValueByWeek>60</xpValueByWeek>
  (Inconsistent xp values. All-time xp should never be smaller than this week’s xp, which should never be smaller than today’s xp.)
4. Test case: <numTaskCompleted>10</numTaskCompleted> <numTaskCompletedByDay>12</numTaskCompletedByDay> <numTaskCompletedByWeek>12</numTaskCompletedByWeek>
  (Inconsistent number of tasks completed. All-time number should never be smaller than this week’s number, which should never be smaller than today’s number.)
5. Test case: <nextDayBreakPoint>12-11-18 0000</nextDayBreakPoint> <nextWeekBreakPoint>19-11-18 0000</nextWeekBreakPoint>
  (Inconsistent date breakpoints. nextWeekBreakPoint should never be earlier than nexDayBreakPoint, it should never be 7 days or more later than nexDayBreakPoint.)
6. Test case: <xp>1000000001</xp>
  (The maximum integer value maintained by achievement record is 1000000000.)

Expected: Due to the invalid data fields, the data file is considered corrupted and task manager is initialized with an empty data file. Task manager will be empty.