Week 11 [Mon, Oct 26th] - Project

tP: v1.5

  1. Alpha-test the product
  2. Fix alpha-test bugs, fine-tune features, improve code quality
  3. Update UG and DG
  4. Settle code authorship
  5. Release v1.5 Thu, Oct 29th 23:59

tP: Release Candidate → v1.5

Intro to tP Week 11

What's happening this week:

v1.5

  • Learning outcome: Able to apply internal quality control.
  • Product goal: Reach the release candidate (RC) version, ready for public beta testing (i.e., the product quality should be sufficiently high, e.g., no obvious bugs).
  • Strategy: Do an internally, and refine features as necessary. Improve tests, documentation, and code quality.

This iteration focuses on applying internal quality control before the product is exposed to outsiders. For example, before beta testers start testing.
In 1, you will do an alpha test of your own product, and record bugs, which can then be fixed during 2.
Keeping in mind that this is your last chance to do any feature enhancements (due to the feature freeze in iteration v1.6), in task 3 you will decide which final touches you want to make, and proceed to implement them.
At the same time, the UG and the DG need to be updated, as given in task 4.

Things to note:

Remind yourself of the project grading criteria:

Admin tP → Grading

1 Alpha-test the product

  1. Create a label alpha-bug in your issue tracker.
  2. Plan the alpha test:
    • Decide who will be testing which feature. Suggested: Assign two members (excluding the feature author) to test each feature.
    • Set a deadline (suggested: should be earlier in the iteration, as you need time to fix the reported bugs).
  3. Start testing as soon as the v1.4 JAR file is ready.
    Test using the JAR file. If you have already added more features since you released v1.4, you are free to do a new release (e.g., v1.4.1) and use that for alpha testing too.
    Use the same steps we use in the PE, reproduced in the panel below.

Admin Practical Exam (Extract) → Steps for testing a tP JAR file

Steps for testing a tP JAR file (please follow closely)

  1. Put the JAR file in an empty folder in which the app is allowed to create files (i.e., do not use a write-protected folder).
  2. Open a command window. Run the java -version command to ensure you are using Java 17.
    Do this again even if you did this before, as your OS might have auto-updated the default Java version to a newer version.
  3. Check the UG to see if there are extra things you need to do before launching the JAR file e.g., download another file from somewhere.
    You may visit the team's releases page on GitHub if they have provided some extra files you need to download.
  4. Launch the jar file using the java -jar command rather than double-clicking (reason: to ensure the jar file is using the same java version that you verified above). Use double-clicking as a last resort.
    We strongly recommend surrounding the jar filename with double quotes, in case special characters in the filename cause the java -jar command to break.
    e.g., java -jar "jar_file_name.jar"
    Note that the name of the JAR file inside the zip file can be different from the one given in their UG. This is because our scripts rename the JAR file using a different naming format before distribution. So, adapt your java -jar command to match the actual JAR file name.
    Windows users: use the DOS prompt or the PowerShell (not the WSL terminal) to run the JAR file.
    Linux users: If the JAR fails with an error labeled Gdk-CRITICAL (happens in Wayland display servers), try running it using the GDK_BACKEND=x11 java -jar jar_file_name.jar command instead.

  1. Report bugs you found, and even suggestions for improvements.
    • If in doubt, report anyway.
    • Apply the alpha-bug label to the bug report, as our grading scripts will look for it when assessing your contribution level for this task.
    • For this individual tP task to be marked as done, you need to submit at least 5 issues labeled alpha-bug i.e., if someone submits 5 alpha bugs, it is marked as 'done' for that person (irrespective of how many alpha bugs other team members submit).

If you want to smoke-test your JAR file on an OS not available within your team, you can post a request in the forum to see if anyone else in the class can help you smoke-test it on that OS.

The panel below contains guidelines your peers will use when determining bugs in the final product -- knowing them might be useful in preventing such bugs in your product in the first place. You may skip the 'General' section.

Some testing tips to get you started (not an exhaustive list)...

  • If your app references date/time of the computer it is running on (e.g., to calculate time elapsed), test whether it works when the computer date/time is configured to be in different formats -- different computers might use different date formats.
  • Test against all typical user mistakes e.g., typing two spaces instead of one
  • If sorting is involved, verify the sorting behavior follows real-world expectations e.g., lexicographical vs alphabetical order
  • Input validation:
    • test valid and invalid inputs, typical and non-typical inputs
    • when a range is involved (e.g., start and end time), test for start-same-as-end and start-later-than-end cases
    • test command parameters: compulsory parameters missing, optional parameters not given, parameters duplicated, unexpected parameters given, typos in parameter names, parameter names appearing inside the parameter value
  • User-visible messages:
    • Are they specific enough? e.g., does the error message indicate what exactly is the error and how to rectify it?
    • Are they consistent with the UG?
    • Are they complete and accurate?
  • Clean up actions:
    • If a feature is supposed to clear/delete data, ensure all relevant data are deleted.
    • If there are multiple windows, ensure all windows are closed when the application exits.
  • Does the application when pushed beyond its limits?
  • UI:
    • Does it work as expected when used in different resolutions and display scaling settings?
    • Does it work as expected when there are many data items, more than the display area can show at a time?
    • When a command is run, do all parts of the UI update as expected? e.g., when an item is deleted, does that item disappear from the list of items currently shown?

2 Fix alpha-test bugs, fine-tune features, improve code quality

  • Fix bugs found during alpha testing.
  • Fine-tune features, if needed.
    Here is another reminder about what you can and can't do during the v1.6 feature freeze.

Ways to level up your tP game:

  • Consider increasing test coverage by adding more tests if it is lower than you would like. Take note of our expectation on test code (given in the panel below).

  • After you have sufficient code coverage, fix remaining code quality problems and bring up the quality to your target level. Note that the quality of the code attributed to you accounts for a significant portion of your final score, graded individually (based on the code attributed to you by the tP code dashboard).
    This is your last chance to improve code quality, given that the amount of code changes you can do during the feature freeze in v1.6 is very limited.

FAQ Must we fix all bugs reported and all enhancements suggested by testers?

FAQ Do we need to change all class/package names that refer to AB3?

3 Update UG and DG

This task is time-sensitive. If done later than the iteration deadline given above, it will not be counted as 'done'.

  • Update the User Guide to match the current version of the product. Reason: testers will need to refer to the UG during the practical exam dry run.
    • Remove mentions of features not implemented yet, if any. As you are not allowed to change features during the iteration v1.6, there is no point keeping those in the UG.
      Alternatively, clearly indicate which features are not implemented yet e.g., tag those features with a Coming soon label.
    • For those features already implemented, ensure their descriptions match the exact behavior of the product e.g., replace mockups with actual screenshots
    • Some things not addressed in the AB3 UG that you might want to consider addressing in your UG (if applicable):
      • Double-clicking the jar might not work on some systems.
      • The app will not work properly if it is placed in a write-protected folder.
      • Mac users using the fullscreen mode for secondary dialogs (e.g., the help dialog) might encounter unexpected behaviors.

  • Similarly, update the Developer Guide (DG).

  • Update the landing page (docs/index.md): Update it to look like a real product (rather than a project for learning SE) if you haven't done so already. In particular, update the Ui.png to match the current product ( tips).

4 Settle code authorship

Do this before the feature freeze begins (i.e., Thu 23:59). Any changes done after that will be subject to the limits of the feature freeze.

  • Ensure your code is and the code RepoSense attributes to you is indeed the code written by you (including code you generated using AI), as explained below:

    • Go to the tP Code Dashboard. Click on the </> icon against your name and verify that the lines attributed to you (i.e., lines marked as green) reflect your code contribution correctly. This is important because some aspects of your project grade (e.g., code quality) will be graded based on those lines.
          

    • More info on how to make the code RepoSense-compatible:

FAQ What if someone took over a feature from another team member?

5 Release v1.5 Thu, Oct 29th 23:59

  • Do a as described in the Developer Guide. Do the release by the given deadline.
    Do a smoke-test to ensure the jar file works.
    • Deliverables:
      1. JAR file (in GitHub releases) -- You may choose any suitable file name, but avoid spaces or special characters in the JAR file name.
      2. Product Website (including UG and DG) (online version)
    • It is optional to write detailed release notes for this version.
  • As before, wrap up the milestone (i.e., reschedule/close any remaining issues/PRs and close the milestone).