CS2103/T - Admin: iP: Week 6

Add Increments: A-BetterGui, A-Personality, A-MoreErrorHandling, A-MoreTesting
Finalize the features
Set up a product website
Submit the final version Fri, Sep 18th 2359

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

As before, we recommend (but do not require) that each increment be done as a separate branch and merged to the master branch when fully done.
You are required to do at least two of the following optional increments, and you should use AI heavily to do them. Even if you have been hand-coding everything until now, this is a good point to give AI-assisted coding a try.

AI Guidance » Add optional enhancements

When appropriate, use AI as a collaborator and idea generator. Instead of simply telling AI what to do, ask AI for ideas on how to proceed. But don't outsource thinking to the AI entirely. Your creativity is what will make your iP different from others -- after all, they are using the same AI tools as you.

Duke A-BetterGui: Better GUI optional

A-BetterGui

↳ Improve the GUI

Improve the GUI to make it more polished. Some examples:

Tweak the GUI to match the asymmetric nature of the conversation: it is between the user and the app, not between two humans, so it makes sense not to display both sides in the same visual format.
Highlight errors, e.g., when the user types a wrong command, the error should be shown in a different format to catch the user's attention.
Tweak padding, fonts, colors, alignments to make the GUI more pleasing to look at.
Given the app is likely to take only a small portion of the screen, and the bot replies can contain a lot of text, try to optimize for space (e.g., avoid wasting display space that simply shows the background graphics).
Allow users to resize the window, and ensure the content responds appropriately.
Profile pictures: If your GUI shows profile pictures, you can tweak the way the picture is shown (e.g., crop as a circle or a square with rounded corners). In fact, an easy tweak is to use a picture with a transparent background so that it blends nicely with the background.
Given that the participants of the conversation are fixed (i.e., you and the chatbot), do you even need big profile pictures?
Focus more on tweaks that actually improve the user experience (UX). Some changes (e.g., profile pictures, background graphics) can be eye-catching but can even degrade the UX if not done right (e.g., it can make the text harder to read).

You can take inspiration from these past projects. If you adopt any ideas from them, don't forget to give credit to the original author.

Minimal requirement: Implement at least one of the examples (i - vi) given above.

Duke A-Personality: A unique personality optional

A-Personality

↳ Give a unique personality

Choose a unique personality for your chatbot, and tweak the following aspects to go with that personality:

Name
Phrases used by your chatbot (e.g., when responding to a command)
GUI (colors, icons, font, etc.)

Duke A-MoreErrorHandling: More error handling optional

A-MoreErrorHandling

↳ More error handling

Improve the code to handle all errors you anticipate the product will encounter during usage.

Some examples of errors:

command format errors: multiple spaces where only one is expected, trailing/leading spaces in the command, an essential parameter missing, a parameter specified multiple times, special characters used where they are not expected, ...
environment issues: an expected file is missing, access to a file is denied, a file's content is not as expected, ...
data is not as expected: start date/time is later than (or same as) end date/time, a value that should be unique is duplicated (e.g., two tasks with the same details), non-existent dates (e.g., Feb 30).

Duke A-MoreTesting: More testing optional

A-MoreTesting

↳ More automated tests

Write more JUnit tests, to cover nearly all code that can be tested automatically.

You may omit code that is hard to test automatically, e.g., GUI functionality (test it manually instead).

This can include more manual testing as well, e.g., testing on different OSes, different screen resolutions, different OS language settings (English vs Chinese).

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 product name is not Duke (as required by Level-0)
and the name is shown correctly everywhere it appears in the UI e.g., the 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.

Reminder about the following:

Limit writing operations to the current folder only. The app should not create files or folders outside the folder from which it is run. In particular, do not store files in the user's home folder.

Reason: This prevents the app from inadvertently corrupting a user's files elsewhere on the disk or filling a tester's disk with files.

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

FAQ What if my iP final submission doesn't meet the bar for full marks? Do I get a chance to resubmit?

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, not UI.png (case-sensitive).
- 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 be 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

A-UserGuide

↳ Add a User Guide

Add a User Guide to the project in the following way:

Update the given docs/README.md. See this guide to GitHub flavored Markdown (GFMD).
Enable the GitHub Pages feature for your fork:
1. Go to your repo's settings tab.
2. Click Pages on the menu on the left edge of the page.
3. Set the Source as: [ Branch: master ] branch and [ /docs ] folder and click Save.
  You can select a theme too.
Go to https://{your username}.github.io/{repo name}/ (e.g., https://[[username: JohnDoe]].github.io/ip/) to view the user guide of your product. Note: it could take 5-10 minutes for GitHub to update the page.
Carefully check the User Guide at the above URL to ensure the HTML version of the page (auto-generated by GitHub Pages from your Markdown text) has the right content. In some rare cases, the page might look alright on GitHub file preview but will not render correctly on GitHub Pages.

Minimal:

Ensure the chatbot name is stated clearly at the top of the User Guide.
Give the reader enough guidance to use all important features of your chatbot.

How detailed should the user guide be? It should be fit-for-purpose: think from the user's point of view, include as much information as the user needs, and keep the guide as short and as friendly as possible -- users don't have the patience for lengthy user guides.
You can use the 'Features' section of this user guide as a benchmark.

AI Guidance » A-UserGuide

Even if you have been updating the User Guide (in docs/README.md) all along, it is worth taking another pass at refining it before releasing your product.

Craft your own prompt to include the important requirements mentioned above.

Review the output from a user's point of view and give feedback to the AI until the user guide meets your expectations.

Once you are happy with the contents, you can ask AI to 'beautify' or 'polish' the appearance of the user guide, for example, by applying appropriate color and font choices. You can also ask it to give me a few design options to choose from to stay in control of the design choices.

Troubleshooting Markdown tables render correctly in GitHub file preview but not in the iP website.

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 username}.github.io/{repo name}/Ui.png (e.g., https://[[username: JohnDoe]].github.io/ip/Ui.png).

Troubleshooting Ui.png is not green in the dashboard even after I've added it to the repo.

4 Submit the final version Fri, Sep 18th 2359

Double-check to confirm your iP meets the criteria for full marks, as given in the panel below.
For example, ensure your Git Standard tag is green in the iP progress dashboard, as it is a necessary condition for you to receive full marks.

Admin iP - Grading

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 on a computer that has Java 25. Do not upload multiple JAR files. To avoid version compatibility issues, we strongly recommend the following approach:
  - Open a terminal window and navigate to the root of your project folder.
  - Run the java -version command to confirm the terminal is using Java 25.
  - Run the ./gradlew clean shadowJar command to create the JAR file.
Do the following smoke tests to ensure the JAR file works (reason: a similar flow will be used when grading your iP).
- 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.
- Pass the JAR file to team members and ask them to do a test drive. Assuming some of your team members use a different OS from yours, this should verify if the app is cross-platform.
  If you don't have ready access to a specific OS, you can ask others to help smoke-test it by posting a smoke-testing request in the forum -- 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.

Troubleshooting My JAR file works on my OS, but not on other OSes

Troubleshooting Error when running JAR file: JavaFX runtime components are missing

Troubleshooting Error when running JAR file: Error initializing QuantumRenderer: no suitable pipeline found

Troubleshooting Error when running JAR file: ... compiled by a more recent version of the Java Runtime

Create a new release on GitHub (e.g., v0.2) and upload the JAR file.

Your GitHub username : GitHub Avatar
Note: Type your GitHub username in the blank above so that we can customize sample commands to fit you.

There is no need for the release to be tagged A-Release specifically.
Ensure your release appears at https://github.com/[[username: JohnDoe]]/ip/releases. Use an incognito browser window when checking this URL, to ensure the release is visible to the public.
The JAR file should be uploaded as an 'asset', with the .jar extension. Do not put it inside a zip file.
Avoid uploading multiple JAR files to this release, as this can create extra work for the evaluators. Upload only the JAR file you want to be evaluated as your iP.
If you have multiple iP releases on GitHub, we take the JAR file from the latest release, irrespective of the release name or the tag used. So, feel free to create more releases if you happen to update the code after creating the initial release.

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

The JAR, User Guide, and the code released via GitHub constitute the iP final submission; there is no separate submission on Canvas.

FAQ How to get a deadline extension for the iP final submission?

iP: Week 6

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