PROJECT: CS ModBuddy

title

Overview

CS ModBuddy is a desktop application used for NUS CS undergraduates to plan modules and manage their study plans. It supports basic operations such as adding modules to and removing modules from different semesters. In addition, the user may create multiple study plans, toggle between different versions of the same study plan, classify their modules via tagging, and check requirements on module prerequisites and MC-counts, while assisted by many user-friendly features such as undo/redo, autocomplete and an elegant GUI. The user interacts with it using a CLI, and it has a GUI created with JavaFX. It is written in Java, and has about 30 kLoC. CS ModBuddy is morphed from AddressBook-Level 3.

Summary of contributions

  • Major feature: added version tracking for individual study plans

    • What it does: allows the user to save the state of the current active study plan. Each study plan has its own commit history, which represents a chronological series of states of this study plan. The user can make a commit, i.e. save the current state, and revert to this commit in the future if they so choose.

    • Justification: This feature improves the product significantly because a user may be unsure of the changes they are currently making, and thus may want to revert to a previous state in the future.

    • Highlights: This feature stores a snapshot of a study plan. Every time the user makes a commit, the study plan is cloned and stored in a list of commits corresponding to each study plan. Corresponding JSON storage support was also implemented so that the commits can be stored to local files immediately.

  • Minor enhancements:

    • Enabled the user to add, delete, and switch between multiple study plans.

    • Enabled the user to add and delete non-mainstream semesters (i.e. special terms or Year 5 semesters).

    • Implemented most of the storage classes so that study plans and their associated information can be stored to local files in JSON format.

    • Allowed the user to obtain a recommended study plan with pre-populated modules.

  • Code contributed: [Functional and Test code]

  • Other contributions:

    • Project management:

      • Managed release v1.3 on GitHub and changed the UI screenshot

      • In charge of code quality, scheduling and tracking

      • Hosted most of the project meetings

    • Enhancements to existing features:

      • Updated the GUI panel to display simplified study plan information (Pull request #212)

      • Wrote additional tests to increase coverage from 69% to 74% (Pull request #301)

    • Documentation:

      • Updated the Storage section of the Developer Guide: #314

      • Wrote the Glossary of the Developer Guide (see below)

    • Community:

      • PRs reviewed (with non-trivial review comments): #232

      • Reported bugs and suggestions for other teams in the class (examples: 1, 2, 3, 4, 5)

      • Helped some of my teammates write JSON storage files to support their features (1, 2)

Contributions to the User Guide

Study Plan

Creating a new study plan: newplan

Creates a new study plan with an optional title. The title should contain only ASCII characters, and should not be longer than 20 characters.

Each study plan is assigned a unique ID upon its creation. This ID will remain the same throughout the life of the study plan. The ID will be reset to 1 when all study plans are deleted and the application is restarted.

Format: newplan [TITLE]
Examples:

  • newplan

  • newplan noc half year

  • newplan minor in maths

Deleting a study plan: removeplan

Deletes a study plan with a given ID.
Format: removeplan PLAN_NUMBER
Example:

  • removeplan 4

Listing all study plans: list

Lists all the study plans that the user has created and has not deleted.

Each study plan is assigned a unique ID upon its creation. This ID will remain the same throughout the life of the study plan.

Format: list

Viewing another study plan: viewplan

Shows the study plan with a given ID. The specified study plan will be displayed on the left panel of the GUI as a simplified study plan. This does not activate that study plan, so it is for viewing only.

Format: viewplan PLAN_NUMBER
Example:

  • viewplan 3
    This allows the user to view the study plan with an ID of 3.

Setting another study plan as active: activate

Replaces the current study plan with the specified study plan as the active one.
Format: activate PLAN_NUMBER
Example:

  • activate 2

Editing the title of current study plan: title

Changes the title of the current active study plan. The title should contain only ASCII characters, and should not be longer than 20 characters.

Format: title PLAN_TITLE
Example:

  • title Algo and Graphics

Setting default study plan: default

Generates a study plan with pre-populated modules according to the recommended study plan for a Year one CS student.
Format: default

Version Tracking

Committing edits to a study plan: commit

Saves changes to a study plan with a short commit message.

Even without committing, the module planner is automatically saved to storage after every command is executed successfully. However, commits allow the user to revert to a previous state of the study plan.
The user is allowed, but not recommended, to commit a study plan even when there are no changes since the previous commit.

Format: commit SHORT_MESSAGE
Examples:

  • commit planned until y2s2

  • commit haven’t added UEs

Checking commit history: history

Shows all commit history of the current study plan.
Format: history

Viewing a commit: viewcommit

Shows the version of the current study plan for a particular commit. This does not create a new commit, nor does it return the study plan to a previous version. The commit will be displayed as a simplified study plan.

Format: viewcommit COMMIT_NUMBER
Example:

  • viewcommit 1.1
    This allows the user to view commit 1 of study plan 1 (which is currently active).

Reverting to a commit: revert

Reverts to the version of the current study plan for a particular commit. This creates a new "Revert to" commit and returns the current active study plan back to the state in the specified commit.

The user is allowed, but not recommended, to revert to another "Revert to" commit. This will create a long chain of "Revert to Revert to …​" commit messages.

Format: revert COMMIT_NUMBER
Example:

  • revert 1.1
    Suppose there are commits 1.0, 1.1, 1.2, and 1.3. This allows the user to revert to commit 1 of study plan 1, creating a new commit called 1.4: Revert to "COMMIT_MESSAGE_OF_1.1".

Removing a commit: removecommit

Removes a commit in the current active study plan specified by the commit number.
Format: removecommit COMMIT_NUMBER
Example:

  • removecommit 2.2

Semester

Adding a semester: addsem

Adds a non-mainstream semester (i.e. special term or Year 5 semester) to the current active study plan.

The user is not allowed to add a mainstream semester. The eight default semesters will always be displayed on the GUI.

Format: addsem SEMESTER
Example:

  • addsem y5s1

Removing a semester from a study plan: removesem

Deletes all the modules in the specified semester in the current active study plan, after which that semester will contain no modules. If the semester to be deleted is a mainstream semester (i.e. not a special term or a Year 5 semester), an empty semester will remain on the GUI. If the semester is a non-mainstream semester, e.g. Y1ST1, the whole semester will disappear from the current study plan.

Format: removesem SEMESTER
Examples:

  • removesem y2s2

  • removesem y1st2

Contributions to the Developer Guide

(Storage section omitted due to length limit)

Version Tracking

Current Implementation

The version tracking mechanism (or commit mechanism) is facilitated by VersionTrackingManager. It is stored as an instance attribute of a ModulePlanner object. Additionally, it implements the following operations:

  • VersionTrackingManager#getStudyPlanCommitManagerByStudyPlan(StudyPlan studyPlan) — Returns the StudyPlanCommitManager for the specified study plan.

  • VersionTrackingManager#commitStudyPlan(StudyPlan studyPlan, String commitMessage) — Saves the current state of the study plan in its history stored in its corresponding StudyPlanCommitManager, together with a commit message.

  • VersionTrackingManager#deleteStudyPlanCommitManagerByIndex(int index) — Deletes a StudyPlanCommitManager specified by the index of its corresponding study plan.

These operations are exposed in the Model interface as Model#commitActiveStudyPlan(String commitMessage), Model#deleteStudyPlanCommitManagerByIndex(int index) etc.

Given below is an example usage scenario and how the commit mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionTrackingManager will be initialized with the initial module planner state, and its StudyPlanCommitManagerList will only contain a manager for the default study plan.

VersionTrackingClassDiagram

Step 2. After changing the state of the current active study plan (e.g. by calling addmod cs1101s y1s1), the user executes commit first draft command to save the current state of this study plan with the commit message first draft. The commit command calls Model#commitActiveStudyPlan(String commitMessage), causing the modified state of the current active study plan after the execution of the commit first draft command to be cloned and saved in the StudyPlanCommitManager corresponding to this study plan, inside the VersionTrackingManager under ModulePlanner.

CommitStudyPlan

Step 3. The user executes revert 1.0 to revert to the commit indexed by 0 in the active study plan which has an ID of 1. The revert command also calls Model#revertCommit(int studyPlanIndex, int commitNumber), causing the state of the study plan stored in this commit to be made active, and this reverted state to be saved into the StudyPlanCommitManager inside the VersionTrackingManager as a revert commit.

RevertCommitSequenceDiagram

(simplified diagram to reduce clutter; revertToCommit is abbreviated as revert etc.)

If a study plan does not have any commit history, it will not call Model#revertCommit(int studyPlanIndex, int commitNumber), so that no commit will be made active. Instead it will prompt the user to create commits first.

Step 4. The user now decides that there is a commit that they want to delete from the history completely, and decides to delete that commit by executing the removecommit command. The removecommit command will call Model#deleteCommit(int studyPlanIndex, int commitNumber), which will delete the commit specified by the commitNumber from the history of the study plan with ID studyPlanIndex.

If the commit number entered does not refer to a valid commit (e.g. there is no commit at all or the index is out of bounds), no deletion will take place. Instead the user will be prompted by an error message.

The following activity diagram shows how the removecommit operation works:

DeleteCommitActivityDiagram

Design Considerations

Aspect: How commit executes

  • Alternative 1 (current choice): Saves the entire state of the study plan at the moment of commit.

    • Pros: Easy to implement.

    • Cons: May have performance issues in terms of memory usage.

  • Alternative 2: Only saves the difference of the current state from the state of the last commit.

    • Pros: Will use less memory (e.g. for addmod, just store the module being added).

    • Cons: We must ensure that the differences in states are stored and loaded correctly when we switch between commits.

Aspect: Data structure to support the commit commands

  • Current choice: Use a list to store the history of commits for each study plan.

    • Pros: Easy to implement. Each study plan has a clear history of its own.

    • Cons: Hard to handle the possibility of branching (which is currently disallowed).

Use case: UC03 - Commit a study plan

MSS

  1. Student requests to save the current version of the study plan.

  2. ModBuddy confirms that the version has been saved.

    Use case ends.

Extensions

  • 1a. ModBuddy detects that there have been no changes to the study plan from the previous commit.

    • 1a1. ModBuddy informs Student that the current version has already been saved.

      Use case ends.

Appendix A: Glossary

Active study plan

The study plan that is currently editable by various commands. Also known as the active plan for short.

CLI

Abbreviation for Command Line Interface, which is a text-based user interface used to view and manage information related to study plans in our application.

Command

An instruction that the user enters into the text input field of our application. A valid command will result in a successful operation on viewing or manipulating the study plan(s).

Commit

A version of a study plan that the user saves to a local file. The user may opt to view or revert to a particular version of any study plan.

Co-requisite

Co-requisites are modules that are to be taken concurrently.

CS

Abbreviation for Computer Science, the study of processes that interact with data and that can be represented as data in the form of programs. In particular, CS here refers to the course for Bachelor of Computing in Computer Science (with Honours) offered by School of Computing (SoC), National University of Singapore (NUS).

Current Semester

The semester in which the user is currently taking modules. All modules taken before the current semester are considered completed.

Default study plan

The recommended study plan for a CS freshman, pre-populated with core modules arranged in their recommended semesters of study.

Elective

Refer to UE.

Feasibility

The feasibility of a study plan, or part of a study plan, refers to whether the following conditions are met:

  • All modules are taken after their prerequisites have been taken.

  • All modules are not taken together with any of their respective preclusions.

  • The user, by following this study plan, satisfies their graduation requirements and will be able to graduate without extending their candidature in NUS.

Focus area

CS modules are organised into Focus Areas of coherent modules according to technical areas of study. A CS Focus Area is satisfied by completing 3 modules from the Area Primaries, with at least one module at 4000-level or above. CS Foundation Modules (CFM) that appear in the Area Primaries can be counted as one of the 3 modules towards satisfying a Focus Area. In this case, a student has to read just two other modules in the Area Primaries to satisfy the Focus Area. The ten Focus Areas are listed below:

  • Algorithms & Theory

  • Artificial Intelligence

  • Computer Graphics and Games

  • Computer Security

  • Database Systems ...
    (For the full version, please refer to Developer Guide#Glossary)