This site is from a past semester! The current version will be here when the new semester starts.

Week 6 [Fri, Feb 16th] - Project

iP:

  1. Add Increments: A-BetterGui, A-Personality, A-MoreErrorHandling, A-MoreTesting, A-AiAssisted
  2. Finalize the features
  3. Set up a product website
  4. Submit the final version Fri, Feb 23rd 2359

tP:

  1. Conceptualize v1.2
  2. Draft the feature specification
  3. Set up the project repo
  4. Get familiar with the code base

iP

1 Add Increments: A-BetterGui, A-Personality, A-MoreErrorHandling, A-MoreTesting, A-AiAssisted

  • As before, we recommend (but not require) that each increment is done as a separate branch and merged to the master branch when ready fully done.
Duke A-BetterGui: Better GUI optional
Duke A-Personality: A unique personality optional
Duke A-MoreErrorHandling: More error handling optional
Duke A-MoreTesting: More testing optional
  • If you are already following the iP.AI route, you may add the A-AiAssisted tag to the latest commit of your repo without any other work.
  • Otherwise (i.e., if you haven't been using AI tools in the iP until now), the increment below is an opportunity for you to use the iP to explore how AI tools can help with programming tasks. If you take it up, in places where you use code that you wrote with the help of AI tools, give some details (e.g., which tool you used how it helped) as a code comment. Alternatively, you can add an AI.md file, similar to the iP.AI route.
Duke A-AiAssisted: Enhance using AI tools optional

2 Finalize the features

  • You may give the product any name, but do not rename the repo.
  • Reminder: you can give the chatbot any personality (there is no need to follow the exact command/response formats given)
  • Ensure that the name of the product name is not Duke (as required by Level-0).
    Ensure the correct product name appears everywhere in the UI e.g., titlebar of the GUI.
  • Remember to give credit to any code you reused or solutions you adopted from others. Reuse without giving credit is plagiarism and will be reported to the university for disciplinary action.

3 Set up a product website

  • Add a representative screenshot of the product to the docs folder.
    • The file should be in the docs folder and named Ui.png exactly (even if the file format is not png, name it png)
    • Ui.png should show the full GUI window (i.e., not just the part containing the chat messages).
    • Ui.png should be a single GUI window (i.e., do not stitch multiple screenshots together).
    • Ideally, the product name should visible in the screenshot e.g., in the title bar of the Window
    • Also note the tips given in the panel below:

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

  • If you added the Ui.png correctly and set up the product website correctly, you should be able to see your screenshot in the iP Showcase page (a link to the iP Showcase page is also available in the top navigation menu → Links) and you should be able to access the image using the link https://{your user name}.github.io/{repo name}/Ui.png (e.g., https://johndoe.github.io/ip/Ui.png).

4 Submit the final version Fri, Feb 23rd 2359

  • Soft deadline: midnight before the tutorial
  1. Double-check to confirm your iP meets the criteria for full marks:

Admin iP - Grading

  1. Create a new jar file
    • Create the JAR file using Gradle -- this needs to be a fat JAR file (hence, it's best created using Gradle's shadow plugin).
    • The JAR file should be cross-platform and should work in a computer that has Java 11 (but no other Java version). To avoid version compatibility issues, we strongly recommend the following approach:
      1. Open a terminal window, and navigate to the root of your project folder.
      2. Run the java -version command to confirm the terminal is using Java 11.
      3. Run the ./gradlew clean shadowJar command to create the JAR file.
  2. 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.
      If you don't have ready access to a specific OS, post a link to your JAR in the forum and ask others to help with the smoke testing -- some of them will even appreciate the opportunity to help a classmate.
      Note that concepts you encounter while doing course project tasks (e.g., smoke testing) are in the scope of the final exam.
  3. 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

tP: Conceptualize the product

tP tasks progress is graded. Completing individual and team tasks are considered for grading the project management component of your project grade. That said, unless a deliverable is marked 'time-sensitive', there is no penalty for missing a deadline provided you catch up with most of them within a few days after the deadline.

Most aspects of project progress are tracked using automated scripts. Please follow our instructions closely or else the script will not be able to detect your progress. We prefer not to waste admin resources processing requests for partial credit for work that did not follow the instructions precisely, unless the progress was not detected due to a bug in the script.

Iterative means no need for detailed plans, right?

Continuing from the points raised in the 'Sidebar: Project planning, with a twist' last week ...

Iterative projects typically do not start with a very detailed plan for the final product, because an iterative project accepts that the project requirements can change along the way and hence it is futile to create detailed plans of the final product at the very start.

However, it does not mean we simply keep adding features without any plan and whatever we have at the end is the final product. Instead,

  1. we should have a clear overall direction (e.g., target user, value proposition), and,
  2. we should start each iteration with a clear, detailed, and precise plan of the intended outcome of that iteration.

Even the plan of the current iteration can change as the iteration progresses (e.g., if we realize we underestimated the effort required for that iteration), but that would be a case of 'changing the current iteration plan', not a case of 'making it up as we go'.

1 Conceptualize v1.2

  • Based on your user stories selected previously, conceptualize the product in terms of how it will look like at v1.2 in the form of a feature list.
    Note down the feature list in your online project notes document.

FAQ: How many features should we put in v1.2?
A: Aim for the smallest set of features the product cannot do without. Even a most basic version of those features is enough. After completing that feature set, you can add more if there is time left.

2 Draft the feature specification

This task is time-sensitive. If done later than the deadline, it will not be counted as 'done' (i.e., no grace period). Reason: This is 'an early draft'; if done late, it can't count as 'early'.

  • Deadline: Recommended to finish by the regular weekly project deadline (i.e., before the next weekly briefing), but given the iP final submission is due this week, you may take until Sunday (Sun, Feb 25th 2359) to submit this.

  • Objective: This deliverable links back to the following point made earlier:

    1. ...
    2. we should start each iteration with a clear, detailed, and precise plan of the intended outcome of that iteration.

    Furthermore, this deliverable forces you to make some fine-grained product design decisions early, thus giving you a better idea about the complexities that lies ahead, and hence, a better sense of the effort that will be required.

  • Deliverable: Collate into a document the complete detailed description of the intended behavior of the product at v1.2.

    • The intended audience for this document is team members, not end users (i.e., this is not a user guide).
    • Use a medium that is convenient for collaboration (e.g., a GoogleDoc).
    • The content need not be polished. Don't waste time in formatting, copy editing etc.

  • For each feature, specify the following:

Purpose: What it does

Command format: The precise command format of the command.
Example commands (to show how the command is used)

For each parameter, specify:

  • Acceptable values e.g., If a command takes a person name as a parameter, what inputs are accepted as valid person names? Some example aspect to consider:
    • Which formats are allowed for dates, times, telephone numbers, etc.?
    • How does extra/leading/trailing spaces affect the value -- for instance is 'John Doe' same as 'John   Doe' (note the multiple spaces in the second name)?
    • How does UPPER/lower case affects values -- is John Doe same as john doe?
    • It's not enough to state 'valid name'; you need to specify what rules will be used to determine if the input is a valid name.
  • Error message if the value is not acceptable
  • Rationale for any the validity rule e.g., why only certain characters are allowed for person names?

Yes, making these decisions is not easy -- and that's why we want you to think about them now rather than later. Feel free to discuss these validation rules in the forum.

Outputs: Precise expected outputs when the command,

  • succeeds e.g., changes in the GUI, messages shown to the user
  • fails e.g., what are the error messages shown when a specific parameter is invalid, missing, specified multiple times, etc.

Duplicate handling: What rules are used to determine if two contacts are duplicates? e.g., is having the same name enough, or all details need to be the same?
How does the application react to such duplicate entries? Reject or accept? Why?

Relevant UI mock-ups, unless the UI will be exatly the same as AB3 (they can be hand-drawn or created using a tool such as PowerPoint, PlantUML, Figma, etc. -- they can be very low-fidelity mock-ups, as they are meant to be temporary)

Recommended: Prioritize above finer aspects of features, for example, as must-have (to implement in v1.2) and nice-to-have (i.e., to implement in v1.2 only if there is time)
e.g., you can decide one date format (to accept in user commands) as must-have and two other formats as nice-to-have.

  • It is OK to make compromises when making product decisions as every design option has costs and benefits, and sometimes, costs outweigh the benefits.
    For example, it is fine to restrict the person name to a certain length and a character set even if it is theoretically possible for those restrictions to conflict with some real-world person names. But you need to be aware of such conflicts, justify the restriction (e.g., ease of implementation/display), and know how users can work around such a conflict should they encounter it (e.g., if you app doesn't allow two contacts to have the same name but the user need to store two contacts which are different people with the same name, what should the user do?).

  • You are welcome to (but not required to) follow AB3 when defining the behavior of the new features e.g., use similar command formats, input validation rules, error message formats.
    Should the feature specification include features already in AB3?
    Yes. But you may copy-paste parts of the UG onto your feature spec if that helps.

  • Ensure feature-fit: While doing this, ensure the features written by each member fit together to form a cohesive product, and meet other grading criteria of the product design aspect. This might require several rounds of refinement. You are encouraged to peer-review feature details written by other team members and refine the overall product design together.

  • Submission [one person per team]: Save the file as a PDF file, name it {team-id}.pdf e.g., CS2103-T09-2.pdf, and upload to Canvas.
  • Grading criteria: to be considered 'done', the feature spec. should meet all the following criteria:
    • Covers all features in the smallest set of features the product cannot do without.
    • Contains all details mentioned above for each of those features
    • Details seem well-thought-out (i.e., not a half-hearted attempt to satisfy the expected level of details)

Recommended: Divide among team members equally; preferably based on enhancements/features each person would be adding e.g., If you are the person planing to add a feature X, you should be the person to describe the feature X in the User Guide and in the Developer Guide.

Reason: In the final project evaluation your documentation skills will be graded based on sections of the User/Developer Guide you have written.

If you are not sure what we mean by 'enhancements/features each person would be adding' mentioned above, see the panel below for our recommendation on how to divide the tP work:

3 Set up the project repo

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

4 Get familiar with the code base

FAQ: Is this a team task or an individual task?
A: It's an individual task (note the icon above), to be done by each member, as we want every member to be familiar with the code base.

Ideally, you should do this task in this week, but you may take an extra week (i.e., by week 7) to finish.

  • Do the following tutorials to get familiar with the codebase
    • Tutorial 1 - Tracing a Command Execution Path
      • We recommend that you put in a sincere effort into this tutorial because tracing through the code of an unfamiliar code base is an important skill that you will not be able to learn/practice it later in the project as the code will no longer be 'unfamiliar' to you later.
      • Submission [optional]: Post an issue in your team's repo with the title Tutorial: tracing code. In the description, add a 2-3 screenshots you took while at various points of the tutorial. You may close the issue soon after.
    • Tutorial 2 - Adding a new Command
      • If you are an experienced programmer, you can add a different command than the one given in the tutorial.
      • Submission: Do your changes in a branch named tutorial-adding-command, push to your fork, and create a PR from your fork to your team's repo. You may close the PR soon after.
      • FAQ: Do we have to write/update test cases too?
        A: Not a strict requirement, but given the purpose of this tutorial is to learn the code base, it's ideal if you do. It will familiarize you with the existing testing infrastructure. Otherwise, you can run into difficulties when you are writing test cases for your own features later.
    • Tutorial 3 - Removing a field from an entity
      • This tutorial is optional to do, but at least give it a quick read.
      • Submission: not required.
  • The PRs created for tutorials need not be merged, unless the changes are actually in line with your project idea.
  • For reference, given below is the workflow you should follow when merging code in your tP: