Week 8 [Mon, Oct 5th] - Project

iP:

  1. Evaluate two peer iPs Sat, Oct 10th 2359

tP: v1.2

  1. Divide MVP features among members
  2. / [Optional] Rename packages/classes
  3. Add the first functionality increment Thu, Oct 8th 23:59

iP

1 Evaluate two peer iPs Sat, Oct 10th 2359

This activity is worth 2x2=4 participation points.

  1. Wait for the email that tells you which iPs have been allocated to you for evaluation. The allocation will also be posted in the course announcements.
  2. Download the latest JAR file for the first iP from the provided link.

FAQ What if the student has not uploaded a JAR file, or the JAR file doesn't work at all?

  1. Locate the app's User Guide by following the link provided in that email.
  2. Open the Canvas survey (the one named iP Peer Evaluation 1) that you will use to submit your evaluation, and note the items you need to evaluate.
  3. Run the JAR file as follows:
    • Put the JAR file in an empty folder.
    • Open a terminal and navigate to the folder where you put the JAR file
    • Run the java -version command to confirm you are using Java 25.
      Mac users, confirm you are using the exact Java distribution we have prescribed here.
    • Run the JAR file using the java -jar "{file_name}" command (rather than double-clicking) in the same terminal. 
      java -jar "my task manager.jar"
  4. Do some light testing of the app (no more than 10 minutes) to ensure the claimed features actually exist and there are no obvious bugs.
  5. Do a quick examination of the code (~ 5 minutes) by following the provided link.
  6. Submit your evaluation using the survey.
  7. Repeat the above steps for the second iP allocated to you (use the iP Peer Evaluation 2 survey).
    If both iPs crash or fail severely in the same way, the problem may be on your side. Please contact the teaching team to ask how to proceed.
  8. Take note of the effort required for a typical iP as this will be helpful in estimating the required tP effort.

tP: First Feature Increment → v1.2

Intro to tP Week 8

What's happening this week:

Now that you have practiced the workflow in the previous iteration, this week's iteration v1.2 adds the first wave of functional code changes.

v1.2

  • Learning outcome: Able to update functional code while working in parallel.
  • Product goal: Take the first step toward an MVP by delivering at least some functionality changes.
  • Strategy: Define the smallest possible MVP (simplest versions of must-have features only). Each member tries to merge at least one PR that moves the product toward that MVP.

The breadth-first iterative approach requires each intermediate version to be a full working product. However, to make things a bit easier for you (as you are only getting started with the project), you need not release any new product version at the end of this iteration. This means you have the freedom to create PRs for small code changes, without the pressure to implement a feature end-to-end within one PR (or even within this iteration).

Things to note:

  • Read our reuse policy (in Admin: Appendix B), in particular, how to give credit when you reuse code from the Internet or classmates:
  • Note the individual and team expectations of the tP, if you haven't done so already.

COMMON MISTAKE: Not following the required phrasing style for the first sentence of Java method header comments.

1 Divide MVP features among members

Although the MVP version is scheduled to be released in v1.3 and not in the current iteration v1.2, in this task we refine the MVP features and divide them among the team members .

  • Re-confirm MVP feature design. Revisit your MVP feature list that you decided in a previous week. Refine it if necessary to ensure the following.
    • It consists of not only
      the most essential features of the target product, but also
      the simplest implementation of those features.
    • It will still be a .
  • Decide which team member implements which feature.
    Reminder: We recommend that the work be divided primarily based on features/enhancements, not by components.

FAQ What if the MVP feature list is smaller than the team size? How to divide work?

Ways to level up your tP game:

Avoid from the start the feature flaws and implementation bugs in the panels below that could cost you marks if they remained in the final version.
Especially note the part on overzealous input validation, which is a common issue found in tPs.

Admin tP: Practical Exam (PE) → Guidelines for bug triaging (extract 1)

Triaging functionality bugs
  • Problems caused by extreme user behaviors:
    • If the problem happens only in cases of deliberate sabotage (e.g., user entered a 30-digit telephone number), it will not be considered a bug (in our context).
      However, if it is possible for a user mistake to cause such inputs (e.g., the user missed typing the space between two parameters), they should not cause harm; for example, such mistakes should not crash the app, corrupt the data, or make it unusable.
    • Problems caused by integer overflows -- apply the guideline in the previous point.
  • Problems caused by very long input values: When user input is unusually long e.g., a very long name, a very large number, it can cause problems; for example, the UI layout can get messed up, or some part of it might get cut off.
    • These can be considered cosmetic issues (i.e., severity.VeryLow) of type.FunctionalityBug (or of type.FeatureFlaw, depending on the nature of the problem).
      However, if the problem can hinder the user (e.g., not seeing the last part of a very long name might not hinder the user, but it does hinder the user if only the first few characters of the name are shown), the severity can be Low or higher.
    • It is also fine to restrict the size/length of inputs as long as the limits are reasonable. For example, limiting the phone number to 8 digits is not reasonable unless you are targeting users whose telephone numbers are guaranteed not to be more than 8 digits.
  • Use of symbols in input values: It is acceptable to disallow certain characters in input values if there is a justification (e.g., because using those symbols in an input value makes the command harder to parse), but such restrictions can still be considered FeatureFlaw bugs if they cause inconvenience to the user. For example, disallowing s/o in a person name because / is used as a command delimiter can cause a major problem if the input is expected to match the legal name of the person.
  • Mismatch between the UG and the feature: If the feature behavior needs to be changed, it is either a type.FunctionalityBug or type.FeatureFlaw. But if it is the UG that needs to be updated, it is a type.DocumentationBug.
  • Issues with the output shown in the terminal: While the terminal output is not critical to the functioning of the product, it is expected to 'behave' in a reasonably presentable manner; for example, avoid showing misleading or alarming information to the user who happens to glance at the terminal output. Therefore, issues related to the terminal can be classified at comparatively lower severities and might qualify to be NotInScope.
  • Handling manual edits to the data file: The AB3 UG specifies the current level of support for manually editing the data file i.e., 'if you edit the file correctly, things will work; but if you edit it wrongly, you can lose all data'. At least that level of support should be provided in the product as well. Bugs can be filed in the following cases:
    (a) The product's support for editing the data files is less than that of AB3.
    (b) The UG promises more support than AB3 but the product doesn't deliver that support.
    (c) The data file format is not suitable for manual editing at all (it violates Constraint-Human-Editable-File).

Admin tP: Practical Exam (PE) → Guidelines for bug triaging (extract 2)

Triaging feature-flaw bugs
  • Missing features and problems in how a feature is designed are considered feature flaws, i.e., type.FeatureFlaw.
  • Feature flaws can be claimed as NotInScope if they qualify as per the rules explained earlier, except for these cases:
    • if fixing the feature flaw is essential for the app to be reasonably useful
    • if the feature is implemented to work in a certain way but it could have been implemented to work in a better way (from the end-user's point of view) without much additional effort
  • Bugs related to duplicate detection: Duplicate detection (e.g., detecting if two persons in the address book are the same) is not trivial; often, detecting only the exact string/value matches is not enough. For example, John Doe and john doe are likely to be the same person. Similarly, extra white space (e.g., the user typed an extra space between the two names) is unlikely to mean they are two different persons. Typically, it is best if you can give a warning in such near-match cases so that the user can make the final decision.
    If your app has a duplicate detection feature, make sure its limitations are made clear to the user so that the user is not led to believe that duplicates are being detected while many potential duplicate cases go undetected. Otherwise, it can be considered a type.FeatureFlaw.
  • Overzealous input validation: This is a common problem in UIs designed by programmers, because programmers tend to define 'valid' from a strict data type point of view, whereas it should be defined based on the user's point of view. In general, it is better to warn rather than to block when inputs are not compliant with the expected format, unless accepting such inputs can hinder the operations of the software. Such flexibility can in turn allow the software to be used in ways you didn't even anticipate, while overzealous rejection of inputs can annoy the user:
    Example 1: While your software allows only one phone number in input values, a user might want to input 1234 5678 (HP) 1111-3333 (Office) -- blocking that input might not add any value but allowing it does.
    Example 2: A user might want to enter an appointment/deadline that occurred in the past, just for record-keeping purposes (note how Google Calendar doesn't prevent users from creating events in the past -- instead, it shows the event in a lighter color to warn that it is in the past).
    Such overzealous input blocking can be considered a type.FeatureFlaw.
    However, it is fine (and recommended) to show a warning for such inputs to guard against the deviation being a mistake rather than intentional.
    At the same time, the lack of proper handling of potentially harmful invalid inputs (either blocking or warning) can be considered a type.FeatureFlaw bug too.
  • Specificity of error message: An error message can be correct but not specific enough (e.g., it says the input is 'invalid' without giving the reason, or gives too many possible reasons without pointing out the specific reason). These cases can be considered type.FeatureFlaw.
    Calling an invalid value a 'format error' and vice versa is a severity.Low bug; for example, if a date input is required to be in YYYY-MM-DD format, 2021-13-28 is a format error (reason: MM should be in 1..12) but 2021-02-30 is an invalid input (reason: February doesn't have 30 days). However, issuing an 'Invalid date or incorrect format' error message for such a case (i.e., covering both bases) is acceptable if differentiating between the two qualifies as NotInScope.
  • Unnecessarily complicated (or hard-to-type) command formats can be considered a type.FeatureFlaw as it is expected that the input formats will be optimized to get things done fast. Some examples: using very long keywords when shorter ones would do, making keywords case-sensitive when there is no need for it, or using hard-to-type special characters in the format when it is possible to avoid them. On the other hand, limiting to short but hard-to-remember keywords can be problematic too. A better approach is to support both a short version (easier to type) and a longer (easier to remember) version for a keyword (an example from the Git world: flags --no-verify and -n are equivalent).
  • Case sensitivity: In general, case sensitivity of something should follow the case sensitivity of the real-world entity it represents e.g., as person names are not case-sensitive in the real world, they shouldn't be case-sensitive in the app either. The same applies to search keywords. Incorrect case sensitivity can be considered a FeatureFlaw.
  • A feature that is less useful than it could be is a FeatureFlaw. Some examples related to search features:
    • If search keywords are case-sensitive, the user needs to remember the exact case of the words she is looking for. A case-insensitive search is usually more useful.
    • Applying an AND constraint on search keywords means the user will miss out on potentially useful search results unless she remembers the exact words she is looking for. But if an OR constraint is used, the user can retrieve results even if she mis-remembers some of the search terms (searching for Alice Richards can return both Alice Davidson and Alison Richards, one of which is likely to be what the user was looking for).

FAQ Why not allow the user to input the command one field at a time?

2 / [Optional] Rename packages/classes

  • If you wish to rename AB3 packages/classes to fit your product, this is the best time to do so, and is best done by one person.
    Renaming packages/classes is optional. It is fine to keep the existing ones.

3 Add the first functionality increment Thu, Oct 8th 23:59

Each member is expected to in each .

FAQ Will I lose marks if I couldn't merge any PRs in an iteration?

Prefer smaller PRs.

Example Suppose you are asked to implement a feature F in the current iteration. Instead of creating one big PR for it, you can start with a smaller PR that implements a very VERY simple version of F, followed by a few more PRs that improve F incrementally.

Side reading: [blog post] Small Pull Requests: 6 reasons why they are the best choice.

AI Guidance » AI can help with code reviews

Most AI tools have built-in support for code review. For example, Codex has a built-in Code review plugin. Otherwise, you can simply explain to the AI what help you need. For example, you can ask it to point out violations of the specific coding standard we follow.

You can also get AI to create a project-specific skill tp-code-review and fine-tune it to match your exact needs. Examples:

  1. You can instruct it to check for specific problems such as duplicated code and weak SLAP.
  2. Instead of just reviewing the PR diff on GitHub, you can instruct AI to pull the branch to your repo and do a more holistic review, including testing of the code.

After 'coaching' it through a few PRs, you can use it to take a first pass at reviewing incoming PRs.

Vet AI's PR review before you allow it to post it. Although AI contributed to the review, the review itself is a graded deliverable that you are accountable for. For example, if you allow AI to post 'spammy' or questionable reviews, your team members will mark you down later.

Steps:

  • Select a code change to implement, as follows:
    • Consider the feature that you have been assigned to implement for the upcoming MVP version of the product (which will be released in iteration v1.3, not in the current iteration v1.2).
    • Pick a small code change that you'll need to do to implement that feature, i.e., a small code change contributing toward the feature, not the entire feature itself.
      This code change should take the codebase forward in a meaningful way, without 'breaking' the codebase or existing tests.
  • Implement that code change while following the workflow that you practiced in the previous week. A summary of the steps:
    • Create an issue for it. Assign it to yourself. Assign it to milestone v1.2.
    • Create a PR from a separate branch in your fork. Assign it to v1.2.
    • Get the PR reviewed.
    • Get the PR merged.
    • Close the corresponding issue.
  • Continue to implement code changes (i.e., repeat S1 and S2) that move you toward your MVP feature(s). We recommend creating when implementing code changes with no/low dependency between them.
  • Wrap up the milestone. When the iteration period is over, do the following:
    • Move any pending issues/PRs to the next milestone (i.e., v1.3).
    • Close the milestone.
    • There is no need to do a product release.

FAQ How much code change is 'enough' for this iteration?

FAQ What's the deadline for tP iterations?

FAQ What if we overshoot the deadline for a tP iteration?

FAQ Do we have to update tests when we update functional code?

FAQ PR CI fails because Codecov reports a drop in code coverage. What to do?

FAQ Is it compulsory to keep CI passing?

FAQ Can we PR against a branch other than master, and merge that branch to master in a later iteration?

FAQ Do we need to update user/developer guides to match code changes?

FAQ Are we allowed to deviate from the MVP Feature Specification submitted earlier?

FAQ When refactoring AB3 code, I would like to find the rationale for the current design; how do I do that?

End of tP Week 8

Shocked by iP to tP transition? Around this time you will realize moving code forward in the tP is much slower than in the iP. As discouraging as this might feel, there are several ways this can contribute toward the learning outcomes of this course, and it is not expected to affect your tP grade either.

More on this ...

Feel free to improve AB3 in any way you see fit. While not very 'buggy', AB3 is not meant to be a 'model solution' either. In particular, find and fix any bugs it has. If you are not sure if something is a bug or intended, you can post in the forum to check.
While we are on the topic, also note that the architecture of AB3 doesn't suit every kind of application either. As you gain more experience in other application domains, you will learn different types of architectures to add to the collection of architectures you can consider for future projects. The same goes for the tool chain and the tech stack of AB3. Therefore, do not try to apply AB3 as a template for every other project you encounter in the future.