Week 8 [Mon, Oct 7th] - Project

iP:

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

tP: v1.2

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

iP

1 Evaluate two peer iPs Sat, Oct 12th 2359

This activity is worth 2x2=4 participation points.

  1. Wait for the email notifying you which iPs are allocated for you to evaluate. When the email is sent out, it will also be announced via course announcements.
  2. Download the latest JAR file of the first iP by following the link provided.

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

  1. Locate the User Guide of the app by following the link provided in that email.
  2. Open the Canvas survey (the one named iP Peer Evaluation 1) that you will be using to submit your evaluation and take note of the things you need to evaluate.
  3. Run the jar file in the following manner:
    • Put the jar file in an empty folder
      Reason: prevent data files created by other jar files you tested earlier from interfering with the current jar file.
    • Open a terminal, and navigate to the folder you put the JAR file in (e.g., cd smoke-test/ip1)
      Reason: data files will be created relative to the folder the terminal is currently in.
    • Run the java -version command to confirm you are using Java 17.
      Mac user, 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.
  4. Do a light testing of the app (not 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 2nd iP allocated to you (use the survey iP Peer Evaluation 2).
    If both iPs crash or fail severely in a similar fashion, 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: After seeing two more iPs, you should now be in a better position to estimate how much you need to do for the tP (reason: the expected implementation effort for the tP is estimated with reference to the implementation effort required for a typical iP).

tP: First feature increment → v1.2

Intro to tP Week 8

What's happening this week:

Having 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 towards 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 towards 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), we will not be releasing 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 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, because MVP is the first full product version anyway (i.e., there is nothing earlier that we can aim our plans at).

  • Re-confirm MVP feature design. Recall that you decided on features to include in the MVP version of the product. Revisit that design. Ensure the following (you may refine the MVP feature design if necessary).
    • It consists of not only
      the most essential features of the target product, but also,
      the simplest implementation of those features (e.g., when adding a new feature to track birthdays of contacts, the simplest implementation of it could be simply adding a new text field for the contact).
    • It will still be a working product (i.e., it can be used)
      Reason: As we are following the breadth-first iterative approach, each intermediate version should be a working product.
  • Divide the features among the team members i.e., who will be implementing which feature.
    • Reminder: We recommend that the work to be divided primarily based on features/enhancements, not by components.

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

Ways to level up your tP game:

Consider the feature flaws and implementation bugs in the panels below that could cost you marks if they remained in the final version (these panels are extracts from the final product evaluation instructions given in the practical exam). If they are avoided from the start, there is no need to hunt them down and fix them later.
Tip: 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)

Functionality bugs
  • Problems caused by extreme user behaviors:
    • If the problem happens only in case of a 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 out typing the space between two parameters), they should not cause harm e.g., 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 a user input is unusually long e.g., a very long name, a very large number, it can cause problems e.g., the UI layout can get messed up, 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 is 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 to be not 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 they 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.
  • Handling manual edits to the data file: 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 edited it wrongly, there's no guarantee that things will work'. At least that level of support should be supported in the new product as well.

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

Feature flaws
  • 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 rules explained above, 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 you app has a duplicate detection feature, make sure its limitations are made clear to the user so that users are 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' in 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. Allowing 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 (either blocking or warning) potentially harmful invalid inputs can be considered a type.FeatureFlaw bug too.
  • Specificity of error message: Error messages 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 e.g., 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 a '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 do, or making keywords case-sensitive when there is no need for it, 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 for search keywords. Incorrect case sensitivity can be considered a FeatureFlaw.
  • A features less useful than it can be is a FeatureFlaw. Some examples related to search-related 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 potentially useful search results unless she remembers exactly the 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, Alison Richards one of which is likely to be what the user was looking for).

FAQ Why not allow 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 (i.e., before starting any functionality changes), as such changes cause widespread changes to the codebase, causing many merge conflicts with any other ongoing PRs.
  • Renaming packages/classes is optional. It is fine to keep the existing ones. But if you decide to rename them, do it quickly, and probably best done by one person in one shot (to minimize merge conflicts).

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

Each member is expected to in each .
Reason: As each iteration focuses on a different learning outcome, it is better for you to take part in each of them fully.

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

Prefer smaller PRs.
Reason: The ability to divide work into small yet meaningful PRs is another intended learning outcome.

  • For 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.

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 by the iteration v1.3, not by the current iteration v1.2).
    • Pick a small code change that you'll need to do to implement that feature. This is a small code change contributing towards the feature, not the entire feature itself. Examples: add parser support for a new command word, add a field to the person class.
      This code change should not 'break' the code base though (e.g., it should not refer to a class that you plan to add in a future PR but doesn't exist yet). Ideally, it should not cause any existing tests to break either. That is, the change should take the codebase forward in a meaningful way.
  • 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 more code changes (i.e., repeat S1 and S2) to implement more code changes that move you towards your MVP feature(s). Recommended to create , 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). As we did not plan to release a product version at the end of this iteration, we can freely move any pending work to the next iteration.
    • Close the milestone.
    • There is no need to do a product release.

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

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 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?

End of tP Week 8

Shocked by iP to tP transition? Around this time you will realize how the speed you can implement things in the tP is significantly slower compared to the iP. As discouraging as this might feel, there are several ways this can contribute towards 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 'perfect' either (it is not meant to be a 'model solution'). In particular, find and fix any bugs it has. If you are not sure if something is a bug or an intended behavior, 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 that you can add to the collection of different architectures that 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.