Week 6 [Mon, Sep 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, Sep 20th 2359

tP:

  1. Conceptualize the MVP version
  2. Draft the feature specification Sun, Sep 22nd 23:59
  3. Set up the project repo
  4. Get familiar with the codebase

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 needing any further 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 AI-assisted code, 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

  • Ensure the product can handle common errors , such as the user making an unintentional error in the command, or the data file not being found in the expected location.
  • Ensure that the name of the product name is not Duke (as required by Level-0)
    and the name is shown correctly everywhere it appears in the UI e.g., title bar of the GUI.
    • Reminder: 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)
  • Remember to give credit for 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.

FAQ Can we get another round of automated code quality feedback?

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, Sep 20th 2359

  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 17 (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 17.
      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.
      When running the jar file for smoke testing, instead of double-clicking the jar file, do the following: open a terminal -> navigate to the jar location -> run the java -jar "JAR_FILE_NAME" command.
    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: Define the MVP

Intro to tP Week 6

Connecting the dots so far ...

Previously, we mentioned the following two project planning strategies:

  • We should have a clear overall direction.This ensures we always head in the right direction, even if the final product is not defined precisely yet.
  • An iteration should start by defining a precise target for it, aligned with the project direction. This ensures we always have a concrete target to aim for.

Last week,

  • to help with PS1, we collected potential user stories for the final product.
  • to help with PS2, we selected a subset of those user stories for an MVP version of the product.

What's happening this week:

This week, we focus on two fronts:

  • The first front (which aligns with PS2) moves towards defining a precise target for the first version (i.e., MVP): task 1 translates the selected user stories into a feature list and task 2 expands that feature lists to a more precise feature specification.
  • On the other front, we prepare to start coding work. Tasks 3 (Set up the project repo), and 4 (Get familiar with the codebase) help with that.

Things to note:

  • 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. There will be no partial credit for work that did not follow the instructions precisely, but in most cases you can get the work to be counted simply by rectifying the non-compliance.

1 Conceptualize the MVP version

  • Task: Based on your user stories selected previously, conceptualize the MVP in the form of a feature list.

  • Why?: So far, we have user stories we want to include in the MVP version. But user stories simply tell us user needs. To move towards a product design, we need to design product features of the product can fulfill those user needs.

  • Submission: Note down the feature list in your online project notes document.

FAQ How many features should we put in the MVP?

2 Draft the feature specification Sun, Sep 22nd 23:59

This task is time-sensitive. If done later than the deadline, it will not be counted as 'done' (i.e., no grace period).

  • 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, Sep 22nd 2359) to submit this.

  • Why? In addition to helping towards PS2, this deliverable forces you to make some fine-grained product design decisions early, thus giving you a better idea about the complexities that lie ahead, and hence, a better sense of the effort that will be required.

  • Task: Collate into a document the complete detailed description of the intended behavior of the MVP version of the product.

    • The intended audience for this document is team members, not 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:

Feature: Name of the feature e.g., Add contact
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 middle of the 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 for two contacts to be considered duplicates, 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 exactly 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: Decide priorities of finer aspects of features, for example, as must-have (to implement in the MVP) and nice-to-have (i.e., to implement in the MVP only if there is time)
e.g., you can decide one date format that is to be supported in user commands as must-have and two other formats as nice-to-have.

  • It is OK to make compromises when making product decisions -- 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 rare 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.

FAQ Do we need to include existing AB3 features in the MVP feature spec?

  • 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 so that each person does a non-trivial amount of documentation; 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 wrote.

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

  1. [/ one member] Set up the team org:
    While only one member needs to do this, it may be useful to do this as a team while that member is screensharing, so that others get to see how it is done too.

  1. [/ one member] Set up the team repo (including the issue tracker):

  1. [ each member] Set up individual forks:

4 Get familiar with the codebase

FAQ Is this a team task or an individual task?

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

See here for details.

We recommend that you put in a sincere effort into this tutorial because tracing through the code of an unfamiliar codebase is an important skill that you can learn by doing so; you will not be able to learn/practice 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

See here for details.

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's tutorial-adding-command branch to your team repo's master branch. You may close the PR soon after.

FAQ When doing this tP tutorial, do we have to write/update test cases too?

Tutorial 3 - Removing a field from an entity

See here for details.

This tutorial is optional to do, but at least give it a quick read.

Submission: not required.