This site is from a past semester! The current version will be here when the new semester starts.
CS2113/T 2021 Jan-May
  • Full Timeline
  • Week 1 [Mon, Jan 11th]
  • Week 2 [Mon, Jun 21st]
  • Week 3 [Mon, Jun 28th]
  • Week 4 [Mon, Jul 5th]
  • Week 5 [Mon, Jul 12th]
  • Week 6 [Mon, Jul 19th]
  • Week 7 [Mon, Jul 26th]
  • Week 8 [Mon, Aug 9th]
  • Week 9 [Mon, Aug 16th]
  • Week 10 [Mon, Aug 23rd]
  • Week 11 [Mon, Aug 30th]
  • Week 12 [Mon, Sep 6th]
  • Week 13 [Mon, Sep 13th]
  • Textbook
  • Admin Info
  • Dashboards
  •  Individual Project (iP):
  • Individual Project Info
  • iP Upstream Repo
  • iP Code Dashboard
  • iP Progress Dashboard

  •  Team Project (tP):
  • Team Project Info
  • Reference AB3
  • Team List
  • tP Code Dashboard
  • tP Progress Dashboard
  • Java exercises
  • Report Bugs
  • Forum
  • Gitter (Chat)
  • Instructors
  • Announcements
  • Files (handouts, submissions etc.)
  • Tutorial Schedule
  • Java Coding Standard
  • Git Conventions
  • Forum Activities Dashboard
  • Participation Dashboard
  • Week 7 [Mon, Jul 26th] - Project

    iP:

    1. Add Increment: A-MoreOOP
    2. Add Increments as PRs: Level-8, Level-9, A-JavaDoc
    3. Set up a product website
    4. Submit the final version Fri, Mar 5th 2359

    tP:

    1. Set up the project repo during the tutorial
    2. Plan the next iteration

    iP

    1 Add Increment: A-MoreOOP

    Why more OOP?

    One the increments below asks you to push the design more towards the OOP approach. This is a good point to remind you that OOP is not a silver bullet or always the right choice. While it is the most popular and possibly the right choice for majority of situations, it has plenty of detractors and known problems.

    OOP has been chosen as the primary paradigm for this module and you are expected to try to push it to its limits. That should give you a first-hand experience of OOP's strengths and weaknesses. Furthermore, OOP (or any other paradigm) will appear worse than it really is if not used correctly, and learning to use it correctly in increasingly larger systems is another objective you can aim for in this module.

    We do not prohibit the use of other paradigms, however. For example, if you find a place where the functional approach is better, go ahead and use it. As you know, Java supports functional programming to a certain extent.

    • As in the previous week, commit, tag, and push, as you do the following increments in the master branch (no need to use separate branches).
    Duke A-MoreOOP: Use More OOP

    A-MoreOOP

         Make the code more OOP

    Refactor the code to extract out closely related code as classes.

    • Minimal: Extract the following classes:
      • Ui: deals with interactions with the user
      • Storage: deals with loading tasks from the file and saving tasks in the file
      • Parser: deals with making sense of the user command
      • TaskList: contains the task list e.g., it has operations to add/delete tasks in the list

    For example, the code of the main class could look like this:

    public class Duke {
    
        private Storage storage;
        private TaskList tasks;
        private Ui ui;
    
        public Duke(String filePath) {
            ui = new Ui();
            storage = new Storage(filePath);
            try {
                tasks = new TaskList(storage.load());
            } catch (DukeException e) {
                ui.showLoadingError();
                tasks = new TaskList();
            }
        }
    
        public void run() {
            //...
        }
    
        public static void main(String[] args) {
            new Duke("data/tasks.txt").run();
        }
    }
    
    • Stretch Goal: Consider extracting more classes. e.g., *Command classes (i.e., AddCommand, DeleteCommand, ExitCommand etc.) that inherits from an abstract Command class, so that you can write the main logic of the App as follows:
      public void run() {
          ui.showWelcome();
          boolean isExit = false;
          while (!isExit) {
              try {
                  String fullCommand = ui.readCommand();
                  ui.showLine(); // show the divider line ("_______")
                  Command c = Parser.parse(fullCommand);
                  c.execute(tasks, ui, storage);
                  isExit = c.isExit();
              } catch (DukeException e) {
                  ui.showError(e.getMessage());
              } finally {
                  ui.showLine();
              }
          }
      }
      
      You can get some inspiration from how the code of the addressbook-level2 is organized.

    2 Add Increments as PRs: Level-8, Level-9, A-JavaDoc

    • Note how to merge PRs:

    Let's look at the steps involved in merging a PR, assuming the PR has been reviewed, refined, and approved for merging already.

    Preparation: If you would like to try merging a PR yourself, you can create a dummy PR in the following manner.

    1. Fork any repo (e.g., samplerepo-pr-practice).
    2. Clone in to your computer.
    3. Create a new branch e.g., (feature1) and add some commits to it.
    4. Push the new branch to the fork.
    5. Create a PR from that branch to the master branch in your fork. Yes, it is possible to create a PR within the same repo.

    1. Locate the PR to be merged in your repo's GitHub page.

    2. Click on the Conversation tab and scroll to the bottom. You'll see a panel containing the PR status summary.

    3. If the PR is not merge-able in the current state, the Merge pull request will not be green. Here are the possible reasons and remedies:

    • Problem: The PR code is out-of-date, indicated by the message This branch is out-of-date with the base branch. That means the repo's master branch has been updated since the PR code was last updated.
      • If the PR author has allowed you to update the PR and you have sufficient permissions, GitHub will allow you to update the PR simply by clicking the Update branch on the right side of the 'out-of-date' error message. If that option is not available, post a message in the PR requesting the PR author to update the PR.
    • Problem: There are merge conflicts, indicated by the message This branch has conflicts that must be resolved. That means the repo's master branch has been updated since the PR code was last updated, in a way that the PR code conflicts with the current master branch. Those conflicts must be resolved before the PR can be merged.
      • If the conflicts are simple, GitHub might allow you to resolve them using the Web interface.
      • If that option is not available, post a message in the PR requesting the PR author to update the PR.

    Tools → Git and GitHub →

    Dealing with merge conflicts

    Merge conflicts happen when you try to combine two incompatible versions (e.g., merging a branch to another but each branch changed the same part of the code in a different way).

    Here are the steps to simulate a merge conflict and use it to learn how to resolve merge conflicts.

    0. Create an empty repo or clone an existing repo, to be used for this activity.

    1. Start a branch named fix1 in the repo. Create a commit that adds a line with some text to one of the files.

    2. Switch back to master branch. Create a commit with a conflicting change i.e. it adds a line with some different text in the exact location the previous line was added.

    3. Try to merge the fix1 branch onto the master branch. Git will pause mid-way during the merge and report a merge conflict. If you open the conflicted file, you will see something like this:

    COLORS
    ------
    blue
    <<<<<< HEAD
    black
    =======
    green
    >>>>>> fix1
    red
    white
    

    4. Observe how the conflicted part is marked between a line starting with <<<<<< and a line starting with >>>>>>, separated by another line starting with =======.

    Highlighted below is the conflicting part that is coming from the master branch:

    blue
    <<<<<< HEAD
    black
    =======
    green
    >>>>>> fix1
    red
    

    This is the conflicting part that is coming from the fix1 branch:

    blue
    <<<<<< HEAD
    black
    =======
    green
    >>>>>> fix1
    red
    

    5. Resolve the conflict by editing the file. Let us assume you want to keep both lines in the merged version. You can modify the file to be like this:

    COLORS
    ------
    blue
    black
    green
    red
    white
    

    6. Stage the changes, and commit.

    3. Merge the PR by clicking on the Merge pull request button, followed by the Confirm merge button. You should see a Pull request successfully merged and closed message after the PR is merged.

    • You can choose between three merging options by clicking on the down-arrow in the Merge pull request button. If you are new to Git and GitHub, the Create merge commit options are recommended.

    Next, sync your local repos (and forks). Merging a PR simply merges the code in the upstream remote repository in which it was merged. The PR author (and other members of the repo) needs to pull the merged code from the upstream repo to their local repos and push the new code to their respective forks to sync the fork with the upstream repo.

    • Practice using parallel git branches and PRs, as explained below:
    1. First, do each increment as a parallel branch (follow the branch naming convention you followed earlier branch-Level-8 etc.), but do not merge any.
    2. Then, push each branch to your fork, and create a PR within your fork (i.e., from the increment branch to the master branch). Be careful not to create a PR to the upstream repo. If you did create such a PR by mistake, no worries, just close it yourself.

    Suppose you want to propose some changes to a GitHub repo (e.g., samplerepo-pr-practice) as a pull request (PR). Here is a scenario you can try in order to learn how to create PRs:

    A pull request (PR for short) is a mechanism for contributing code to a remote repo, i.e., "I'm requesting you to pull my proposed changes to your repo". For this to work, the two repos must have a shared history. The most common case is sending PRs from a fork to its upstream repo is a repo you forked fromupstream repo.

    1. Fork the repo onto your GitHub account.

    2. Clone it onto your computer.

    3. Commit your changes e.g., add a new file with some contents and commit it.

    • Option A - Commit changes to the master branch
    • Option B - Commit to a new branch e.g., create a branch named add-intro (remember to switch to the master branch before creating a new branch) and add your commit to it.

    4. Push the branch you updated (i.e., master branch or the new branch) to your fork, as explained here.

    Pushing a branch to a remote repo

    Here's how to push a branch to a remote repo:

    Here's how to push a branch named add-intro to your own fork of a repo named samplerepo-pr-practice:

    Normally: git push {remote repository} {branch}. Examples:

    • git push origin master pushes the master branch to the repo named origin (i.e., the repo you cloned from)
    • git push upstream-repo add-intro pushes the add-intro branch to the repo named upstream-repo

    If pushing a branch you created locally to the remote for the first time, add the -u flag to get the local branch to track the new upstream branch:
    e.g., git push -u origin add-intro

    See git-scm.com/docs/git-push for details of the push command.

    5. Initiate the PR creation:

    1. Go to your fork.

    2. Click on the Pull requests tab followed by the New pull request button. This will bring you to the 'Comparing changes' page.

    3. Set the appropriate target repo and the branch that should receive your PR, using the base repository and base dropdowns. e.g.,
      base repository: se-edu/samplerepo-pr-practice base: master

      Normally, the default value shown in the dropdown is what you want but in case your fork has e.g., the repo you forked from is also a fork of a another repo, which means both of those are considered upstream repos of your forkmultiple upstream repos, the default may not be what you want.

    4. Indicate which repo:branch contains your proposed code, using the head repository and compare dropdowns. e.g.,
      head repository: myrepo/samplerepo-pr-practice compare: master

    6. Verify the proposed code: Verify that the diff view in the page shows the exact change you intend to propose. If it doesn't, commit the new code and push to the branchupdate the branch as necessary.

    7. Submit the PR:

    1. Click the Create pull request button.

    2. Fill in the PR name and description e.g.,
      Name: Add an introduction to the README.md
      Description:

      Add some paragraph to the README.md to explain ...
      Also add a heading ...
      
    3. If you want to indicate that the PR you are about to create is 'still work in progress, not yet ready', click on the dropdown arrow in the Create pull request button and choose Create draft pull request option.

    4. Click the Create pull request button to create the PR.

    5. Go to the receiving repo to verify that your PR appears there in the Pull requests tab.

    The next step of the PR life cycle is the PR review. The members of the repo that received your PR can now review your proposed changes.

    • If they like the changes, they can merge the changes to their repo, which also closes the PR automatically.
    • If they don't like it at all, they can simply close the PR too i.e., they reject your proposed change.
    • In most cases, they will add comments to the PR to suggest further changes. When that happens, GitHub will notify you.

    You can update the PR along the way too. Suppose PR reviewers suggested a certain improvement to your proposed code. To update your PR as per the suggestion, you can simply modify the code in your local repo, commit the updated code to the same master branch, and push to your fork as you did earlier. The PR will auto-update accordingly.

    Sending PRs using the master branch is less common than sending PRs using separate branches. For example, suppose you wanted to propose two bug fixes that are not related to each other. In that case, it is more appropriate to send two separate PRs so that each fix can be reviewed, refined, and merged independently. But if you send PRs using the master branch only, both fixes (and any other change you do in the master branch) will appear in the PRs you create from it.

    To create another PR while the current PR is still under review, create a new branch (remember to switch back to the master branch first), add your new proposed change in that branch, and create a new PR following the steps given above.

    It is possible to create PRs within the same repo e.g., you can create a PR from branch feature-x to the master branch, within the same repo. Doing so will allow the code to be reviewed by other developers (using PR review mechanism) before it is merged.

    1. Now, merge one of the PRs and update the remaining PRs accordingly, as given below:
      1. Merge one of the PRs on GitHub e.g., Level-8. Remember to choose the Create merge commit option when merging.
      2. Pull the updated master branch from your fork to your Computer.
      3. Note how the remaining un-merged branches are no longer in sync with the latest master. To rectify, merge the master branch to each of them. Resolve merge conflicts, if any.
      4. Push the updated branches to your fork. The PRs will update automatically to reflect the updated branch.
      5. As before, tag the merge commit in the master branch and push the tag to your fork.
    2. Merge the remaining PRs using a procedure similar to the above.
    Duke Level-8: Dates and Times optional

    Level 8. Dates and Times

    Teach Duke how to understand dates and times. For example, if the command is deadline return book /by 2/12/2019 1800, Duke should understand 2/12/2019 1800 as 2nd of December 2019, 6pm, instead of treating it as just a String.

    • Minimal: Store deadline dates as a java.time.LocalDate in your task objects. Accept dates in a format such as yyyy-mm-dd format (e.g., 2019-10-15) and print in a different format such as MMM dd yyyy e.g., (Oct 15 2019).
    • Stretch goal: Use dates and times in more meaningful ways. e.g., add a command to print deadlines/events occurring on a specific date.

    A code snippet using the LocalDate class:

    import java.time.LocalDate;
    import java.time.format.DateTimeFormatter;
    import java.time.temporal.ChronoUnit;
    
    public class Main {
        public static void main(String[] args) {
            //create dates from strings
            LocalDate d1 = LocalDate.parse("2019-12-01");
            LocalDate d2 = LocalDate.parse("2019-12-02");
            LocalDate d3 = LocalDate.parse("2019-12-02");
            
            //compare dates
            System.out.println(d1.isBefore(d2)); // -> true
            System.out.println(d1.isAfter(d2)); // -> false
            System.out.println(d2.equals(d3)); // -> true
            
            //work with dates
            System.out.println(d1.getDayOfWeek()); // -> SUNDAY
            System.out.println(d1.getMonth()); // -> DECEMBER
            System.out.println(d1.plus(1, ChronoUnit.YEARS));  // -> 2020-12-01
            
            // get today's date and print it in a specific format
            LocalDate d4 = LocalDate.now();
            System.out.println(d4); // -> 2019-10-15
            System.out.println(d4.format(DateTimeFormatter.ofPattern("MMM d yyyy"))); // -> Oct 15 2019
        }
    }
    
    Duke Level-9: Find

    Level 9. Find

    Give users a way to find a task by searching for a keyword.

    Example:

    find book
        ____________________________________________________________
         Here are the matching tasks in your list:
         1.[T][X] read book
         2.[D][X] return book (by: June 6th)
        ____________________________________________________________
    
    Duke A-JavaDoc: JavaDoc

    A-JavaDoc

         Add JavaDoc comments

    Add JavaDoc comments to the code.

    • Minimal: Add header comments to at least half of the non-private classes/methods.
    • Stretch goal: Add header comments to all non-private classes/methods, and non-trivial private methods.

    3 Set up a product website

    • Add a brief User Guide (UG)
    Duke A-UserGuide: User Guide

    A-UserGuide

         Add a User Guide

    Add a User Guide to the project. Here is one simple way to do it.

    • Update the given docs\README.md. See this guide to GitHub flavored Markdown (GFMD).
    • Go to the settings page of your Duke fork and enable GitHub pages to publish from the docs folder (you can select a theme too).
    • Go to http://{your username}.github.io/{repo name}/ to view the user guide of your product. Note: it could take 5-10 minutes for GitHub to update the page.

    4 Submit the final version Fri, Mar 5th 2359

    • Soft deadline: midnight before the tutorial

    • Create a new jar file

      • Create the JAR file in one of these ways:
        • If you have added a GUI or using third-party libraries: use Gradle.
        • Else: you can use Intellij.
      • The JAR file should be cross-platform and should work in a computer that has Java 11.
    • Do the following smoke tests to ensure the jar file works (reason: a similar flow will be used when grading your iP).

      1. Copy the jar file to an empty folder and test it from there. This should surface issues with hard-coded file paths.
      2. Pass the jar file to team members and ask them to do a test drive. Assuming some of your team members' OS differ from yours, this should verify if the app is cross-platform.
    • Create a new release on GitHub (e.g., v0.2) and upload the JAR file.

      • Recommended to refrain from uploading multiple JAR files as this can cause extra work for the evaluators.
    Duke A-Release: Release

    A-Release

         Release the product

    Release the product to be used by potential users. e.g., you can make it available on GitHub

    tP: Get ready for iterations

    1 Set up the project repo during the tutorial

    • Set up the team org, the team repo, and individual forks as explained below:

    tP Team Organization Setup

    Please follow the organization/repo name format precisely or else our grading scripts will not be able to detect your work.

    (/) Only one team member:

    After receiving your team ID, one team member should do the following steps:

    • Create a GitHub organization with the following details:
      • Organization name (all UPPER CASE) : AY2021S2-TEAM_ID. e.g.  AY2021S2-CS2113T-W12-1, AY2021S2-CS2113-T09-2
      • Plan:  Open Source ($0/month)
      • This organization belongs to: My personal account
    • Add members to the organization:
      • Create a team called developers to your organization.
      • Add your team members to the developers team.

    tP Team Repo Setup

    (/) Only one team member:

    The tP project template given to you is a variation of the iP repo you used for the iP, but with some important differences. Please follow instructions carefully, rather than follow what you remember from the iP.

    1. Fork the https://github.com/nus-cs2113-AY2021S2/tp repo to your team org.

      • This repo (let's call it the team repo) is to be used as the repo for your project.
      • Please do not rename the fork Reason: our grading scripts rely on the repo name.
    2. Enable the issue tracker.

    3. Enable GitHub Actions: Go to the Actions tab and enable workflows by clicking the button. That will enable the GitHub Actions that are already included in the repo you forked.

    4. Enable GitHub Pages: Go to the Settings tab and enable GitHub Pages for the master branch /docs folder (similar to how you did it in the iP).
      Remember to choose a theme too by clicking the button (that will create a commit in your repo that is needed in a later step.
      After a few minutes, confirm your tP website is available in the corresponding github.io URL.

    5. Add members. Ensure your team members have the desired level of access to your team repo.
      Recommended: Give admin access to 1-2 members and write access to others.

    6. Create a team PR for us to track your project progress: i.e., create a PR from your team repo master branch to [nus-cs2113-AY2021S2/tp] master branch. PR name: [Team ID] Product Name e.g., [CS2113-T09-2] InsureList. As you merge code to your team repo's master branch, this PR will auto-update to reflect how much your team's product has progressed.
      Please fill in these details as specified because they are used by our grading scripts.

      • PR subject: the name of your product e.g., [CS2113-T09-2] InsureList
      • Description: a 1-2 sentence overview (plain text only, no formatting or links) of your project indicating the target user and the value proposition e.g., InsureList helps insurance agents manage detail of their clients. It is optimized for CLI users so that frequent tasks can be done faster by typing in commands.

    tP Individual Fork Setup

    (, , , ...) Every team member:

    1. Watch the tp repo (created above) i.e., go to the repo and click on the button to subscribe to activities of the repo.
    2. Fork the tp repo to your personal GitHub account.
      Please do not rename the fork Reason: our grading scripts rely on the repo name.
    3. Clone the fork to your computer.
    4. Set up the developer environment in your computer by following the the README carefully as the steps are different from the iP.

    Do not alter these paths in your project as our grading scripts depend on them.

    • src/main/java
    • src/test/java
    • docs

    2 Plan the next iteration

    • Plan the next iteration. As you know, you should follow the breadth-first iterative process. Therefore, first you must decide what functionalities should be in the product if you had only two weeks to implement it. You have done that already when you chose user stories for v1.0, translated that to features, and even drafted the UG based on those features. You can tweak that plan further at this point if you wish, given that you now have some idea of how fast the team can work when using the prescribed workflow.
      • Aim to produce a working MVP at the end of this iteration even if the functionalities are not polished (polishing can be done in a later iteration).
      • If possible, break the iteration into two increments i.e., aim to produce an even simpler but working version after one week.
      • Avoid depth-first implementations: "I'll do the back-end part of feature X in this iteration" is not acceptable as that is not in the spirit of iterative development. Remember, we are pretending this to be the last iteration; why would you implement the back-end part of a feature in the last iteration?
        It is OK to add simpler versions of bigger features, but not OK to add partial features that can't be used yet.
    • Divide the work among the team members i.e., the work required for the current iteration.
    • Reflect the above plan in the issue tracker by assigning the corresponding issues (create new issues if necessary) to yourself and to the corresponding milestone. For example, the user story pertaining to the increment show a place holder for photo, showing a generic default image should be assigned to Jake and to milestone v1.0
      Optionally, you can define a mid-v1.0 milestone to keep track of things to be done within the first half of the milestone.