Week 11 [Mon, Oct 28th] - Project

tP: v1.5

  1. Alpha-test the product
  2. Fix alpha-test bugs, fine-tune features
  3. Update UG and DG
  4. Release v1.5 Thu, Nov 7th 23:59

tP: Release candidate → v1.5 → 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 a 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, code quality.

This iteration focuses on applying internal quality control before the product is exposed to outsiders. 'Outsiders' here refer to other teams that will be testing your product during the practical exam dry run (PE-D).
In 1, you will do an alpha testing 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 would want to implement, and proceed to implement them.
At the same time, the UG and the DG needs to be updated, as given in task 4.

Things to note:

This iteration is normally done in one week, but is spread over two weeks due to clashes with holidays. So, do the amount of work you would normally do if this was only one week long (i.e., no need to do more work because there is an extra week for this iteration).

Remind yourself of the project grading criteria:

Admin tP → Grading

1 Alpha-test the product

-- [More details to be added] --

  • Test based on the JAR file
  • Cross-test, and report bugs
  • Create a label alpha-bug and apply it to the bug report, for tracking

If you want to smoke-test your JAR file on an OS that is 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.

2 Fix alpha-test bugs, fine-tune features

-- [More details to be added] --

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

Ways to level up your tP game:

  • Consider increasing test coverage by adding more tests if it is lower than the level you would like it to be. 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 component of your final score, graded individually (based on the code attributed to you by the tP code dashboard).

3 Update UG and DG

  • 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 any 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.
    • For those features already implemented, ensure their descriptions match the exact behavior of the product e.g. replace mockups with actual screenshots

  • Save the UG as a PDF file using this technique exactly. You'll need this file later when you create a product release. There is no specific file name convention for this version of the UG, but do use a reasonable file name: e.g., Contacts-Pro-User-Guide.pdf.

  • Similarly, update the Developer Guide (DG), and save it as PDF file.

Admin tP Deliverables → DG → Tips
  • Aim to showcase your documentation skills. The primary objective of the DG is to explain the design/implementation to a future developer, but a secondary objective is to serve as evidence of your ability to document deeply-technical content using prose, examples, diagrams, code snippets, etc. appropriately. To that end, you may also describe features that you plan to implement in the future, even beyond v1.6 (hypothetically).
    For an example, see the description of the undo/redo feature implementation in the AddressBook-Level3 developer guide.
  • Use multiple UML diagram types. Following from the point above, try to include UML diagrams of multiple types to showcase your ability to use different UML diagrams.

FAQ Is it enough to update existing UML content/diagrams or must we add new content/diagrams?

  • Diagramming tools:
    • AB3 uses PlantUML (see the guide Using PlantUML @SE-EDU/guides for more info).
    • You may use any other tool too (e.g., PowerPoint). But if you do, note the following:
      • Choose a diagramming tool that has some 'source' format that can be version-controlled using git and updated incrementally (reason: because diagrams need to evolve with the code that is already being version controlled using git). For example, if you use PowerPoint to draw diagrams, also commit the source PowerPoint files so that they can be reused when updating diagrams later.
      • Use the same diagramming tool for the whole project, except in cases for which there is a strong need to use a different tool due to a shortcoming in the primary diagramming tool. Do not use a mix of different tools simply based on personal preferences.
    • Can UML diagrams be used in project submissions? Not a good idea. Given below are three reasons each of which can be reported by evaluators as 'bugs' in your diagrams, costing you marks:
      • They often don't follow the standard UML notation (e.g., they add extra icons).
      • They tend to include every little detail whereas we want to limit UML diagrams to important details only, to improve readability.
      • Diagrams reverse-engineered by an IDE might not represent the actual design as some design concepts cannot be deterministically identified from the code e.g., differentiating between multiplicities 0..1 vs 1, composition vs aggregation.
  • Keep diagrams simple. The aim is to make diagrams comprehensible, not necessarily comprehensive.
    Ways to simplify diagrams:
    • Omit less important details. Examples:
      • a class diagram can omit minor utility classes, private/unimportant members; some less-important associations can be shown as attributes instead.
      • a sequence diagram can omit less important interactions, self-calls, method parameters, etc.
        Tip: You can use ... (e.g., foo(...)) to indicate parameters have been omitted.
        Tip: You can use pseudocode instead of exact method calls e.g., save data in file instead of saveData(content, filename).
    • Omit repetitive details e.g., a class diagram can show only a few representative ones in place of many similar classes (note how the AB3 Logic class diagram shows concrete *Command classes using a placeholder XYZCommand).
    • Limit the scope of a diagram. Decide the purpose of the diagram (i.e., what does it help to explain?) and omit details not related to it. In particular, avoid showing lower-level details of multiple components in the same diagram unless strictly necessary e.g., note how the this sequence diagram shows only the detailed interactions within the Logic component i.e., does not show detailed interactions within the model component.
    • Break diagrams into smaller fragments when possible.
      • If a component has a lot of classes, consider further dividing into subcomponents (e.g., a Parser subcomponent inside the Logic component). After that, subcomponents can be shown as black-boxes in the main diagram and their details can be shown as separate diagrams.
      • You can use ref frames to break sequence diagrams to multiple diagrams. Similarly, rakes can be used to divide activity diagrams.
    • Stay at the highest level of abstraction possible e.g., note how this sequence diagram shows only the interactions between architectural components, abstracting away the interactions that happen inside each component.
    • Use visual representations as much as possible. E.g., show associations and navigabilities using lines and arrows connecting classes, rather than adding a variable in one of the classes.
    • For some more examples of what NOT to do, see here.
  • Integrate diagrams into the description. Place the diagram close to where it is being described.
  • Use code snippets sparingly. The more you use code snippets in the DG, and longer the code snippet, the higher the risk of it getting outdated quickly. Instead, use code snippets only when necessary and cite only the strictly relevant parts only. You can also use pseudocode instead of actual programming code.
  • Resize diagrams so that the text size in the diagram matches the text size of the main text of the diagram. See example.

  • Update the landing page (docs/index.md): Update 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 Release v1.5 Thu, Nov 7th 23:59

  • Do a as described in the Developer Guide. Do the release by the given deadline. Do some manual tests to ensure the jar file works. Include the following files in the release (as separate assets):
    • JAR file
    • UG (PDF file) -- uploaded as an 'asset' (similar to the JAR file), not embedded in the release note.
    • DG (PDF file) -- similar to DG
    • It is optional to write detailed release notes for this version.
  • You can do an additional release before the PE dry run (PE-D) if you wish, as long as you do it before 10 am Friday. That additional release is still considered part of v1.5 and therefore, can contain new features. When doing this additional release, do not delete the previous release (reason: it is good to preserver the release history) -- testers are expected to test the latest release file anyway. You may use any suitable version number for this JAR file e.g., v1.5.1.
    Waiting till Friday 10am to release the v1.5 is strongly discouraged because if you miss that deadline, your team will not be able to benefit from the PE-D at all. It is better to have an earlier release to fall back on in case that happens.
  • The feature freeze will apply at the point you released the JAR file that was used in the PE-D i.e., the features submitted in the final v1.6 two weeks later should be the same as the features tested during PE-D, which is the rationale for the feature freeze anyway.
  • As before, wrap up the milestone (i.e., reschedule/close any remaining issues/PRs and close the milestone).