This site is from a past semester! The current version will be here when the new semester starts.

tP week 10: mid-v1.3tP week 12: mid-v1.4


tP week 11: v1.3

  1. Deliver v1.3
  2. Update user docs
  3. Release as a jar file
  4. Ensure the code RepoSense-compatible
  5. Wrap up v1.3
  6. Demo v1.3 before the tutorial

1 Deliver v1.3

  • Deliver the features that you planned for v1.3.

2 Update user docs

  • Update the v1.3 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.
    • 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
  • 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).

3 Release as a jar file

  • Do a resulting in a jar file on GitHub that can be downloaded by potential usersproper product release as described in the Developer Guide. Aim to release it by the weekly deadline. Do some manual tests to ensure the jar file works.
  • Note that you can do an additional JAR release before the PE dry run if you wish, as long as you do it before 10 am Friday. That additional JAR is still considered part of v1.3 and therefore, can contain new features. When doing this additional release, do not delete the previous one (reason: it is good to preserver the release history) -- testers are expected to take the latest JAR file anyway. You may use any suitable version number for this JAR file e.g., v1.3.1

4 Ensure the code RepoSense-compatible

  • Ensure your code is i.e., RepoSense can detect your code as yoursRepoSense-compatible and the code it attributes to you is indeed the code written by you, 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) reflects 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:

Smoke-test CATcher

  • This activity is compulsory and counts for 3 participation points. Please do it before the weekly deadline.

Some background: As you know, our i.e., Practical ExamPE includes peer-testing tP products under exam conditions. In the past, we used GitHub as the platform for that -- which was not optimal (e.g., it was hard to ensure the compulsory labels have been applied). As a remedy, some ex-students have been developing an app called CAT stands for Crowd-sourced Anonymous TestingCATcher that we'll be using for the PE this semester.

This week, we would like you to smoke-test the CATcher app to ensure it can run in your computer.

Deliver v1.3

  • Deliver the features that you planned for v1.3.

Update user docs

  • Update the v1.3 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.
    • 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
  • 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).

Demo v1.3

  • [one member] As was done in v1.2,
    • Run your application using the JAR file that you released for v1.3.
    • Take screenshots of each available feature in action (or screen-record a demo -- need not be polished).
    • Add those screenshots (or upload the demo video somewhere and give the link) to your collaborative project notes document with an appropriate heading e.g., v1.3 features demo.

Add sequence diagrams to the developer guide

  • Add sequence diagrams to enhance your DG wherever they can be useful. Note that diagrams you add in this week will receive feedback while diagrams added later will not.
  • Try to do this before Wednesday so that the added sequence diagrams can get peer feedback via the DG peer review that will happen during this week's tutorial.

Deliver v1.3

* As before, do a release on GitHub and upload the v1.3 jar file. Do this before the deadline as PE testers will start downloading jar files ahead of time. * ==IMPORTANT: ensure your jar file was generated using Java 11 and can work on all major OS'es using JDK 11.==

  • Wrap up the milestone on GitHub.

Release as a jar file

  • Do a resulting in a jar file on GitHub that can be downloaded by potential usersproper product release as described in the Developer Guide. Aim to release it by the weekly deadline. Do some manual tests to ensure the jar file works.
  • Note that you can do an additional JAR release before the PE dry run if you wish, as long as you do it before 10 am Friday. That additional JAR is still considered part of v1.3 and therefore, can contain new features. When doing this additional release, do not delete the previous one (reason: it is good to preserver the release history) -- testers are expected to take the latest JAR file anyway. You may use any suitable version number for this JAR file e.g., v1.3.1

Wrap up v1.3

  • as before

Review others' DG

  • To be done during the tutorial. Please don't do this task before the tutorial as others need time to update their DGs.
  • Read all instructions before you start the activity.
  • Find the team choices you have been allocated to review, as given in the panel below.

Allocation for DG review

  • Decide which of the given team(s) to review:

    • Open the DG link of the team allocated as 'First choice'.
    • Confirm that the DG has significant updates, to the diagrams in particular. If it doesn't, you can try the DG of the 'Second choice' team, and failing that, 'Third choice' team.
    • If neither one of the three has enough updates but collectively they have enough updates, you can also review all of them.
    • Failing all above, you can pick any other team(s) to review.
    • Try to give at least 4 comments in total.
    • If the PR already has reviews, you can give your own input of the existing review comments too.

  • Go to the PR of the team(s) you have chosen to review.

  • Review the Design and the Implementation sections w.r.t possible DG bugs (given further down); add your observations as comments.

  • In the PR, add review comments (i.e., in the files changed tab) in the corresponding place of the code.
    • In this case, choose the option rather than option.
  • But if the 'files changed' tab is too laggy, you can add a normal comment instead in the conversation tab.
    • In this case, enter each observation as a separate comment (reason: our bot will count the number of comments you have given to determine if you qualify for participation points)
  • As you know, it is better to phrase your comments as question/doubts (e.g., Is this format correct? Should it be ... instead?) rather than directives (e.g., Change this to ...).
    Where possible, use screenshots from their DG in your comments, preferably with annotations. This is particularly useful when commenting on diagrams. An example given below:
  • The understanding you gain from this exercise can indirectly determine how well you do in your own project. Note that your comments will be reviewed by a tutor later.
DG - Possible Bugs

Pay attention to these as they are same as the final evaluation criteria of the DG.

Admin tP Grading → DG Bugs → UML Diagrams → Possible Bugs

UML diagrams:

  • Notation incorrect or not compliant with the notation covered in the module.
  • Some other type of diagram used when a UML diagram would have worked just as well.
  • The diagram used is not suitable for the purpose it is used.
  • The diagram is too complicated.

Admin tP Grading → General Documentation Bugs

Use of visuals

  • Not enough visuals e.g., screenshots/diagrams
  • The visuals are not well integrated to the explanation
  • The visuals are unnecessarily repetitive e.g., same visual repeated with minor changes

Use of examples:

  • Not enough or too many examples e.g., sample inputs/outputs

Explanations:

  • The explanation is too brief or unnecessarily long.
  • The information is hard to understand for the target audience. e.g., using terms the reader might not know

Neatness/correctness:

  • looks messy
  • not well-formatted
  • broken links, other inaccuracies, typos, etc.
  • hard to read/understand
  • unnecessary repetitions (i.e., hard to see what's similar and what's different)

Also see:

Admin tP: Deliverables → DG → Tips

  • Aim to showcase your documentation skills. The stated objective of the DG is to explain the 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.4 (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.
  • 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 i.e., automatically reverse engineered from the Java codeIDE-generated 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.
    • 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 sub-components (e.g., a Parser sub-component inside the Logic component). After that, sub-components 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 pseudo code instead of actual programming code.
  • Resize diagrams so that the text size in the diagram matches the the text size of the main text of the diagram. See example.

  • After the tutorial, if you are unsure about a concern raised by a reviewer, you can post in the forum to seek the opinion of the teaching team.

Attend the practical exam dry run

  • See info in the panel below:

Polish the product as per peer-testing results

Allowed in the v1.4 milestone:

fixing bugs
improving documentation
purely cosmetic enhancements e.g., alignments, style changes
improving code quality
improving tests
removing features

Not allowed in v1.4: adding features or doing major changes to existing features.

The goal of freezing features in the pre-release iteration is to subject the features to at least one round of intensive non-dev testing before they are released to the users. In a real project, minor or critical changes might be allowed even near a deadline -- but here, we do not allow any feature changes because it can start us on a slippery slope and many "is this change allowed?" queries. Therefore, v1.4 should not have any features that was not already tested in the PE-D).

FAQs:

  • Q: Can we add a missing validity check for a user input?
    A: Yes, but only if its absence causes the software to mis-behave (i.e., it's omission can be considered a bug).
  • Q: Testers have reported a missing feature (or a feature suggestion). Can we add it?
    A: Most teams receive such suggestions from testers as we allow feature suggestions in PE-D (but they are not allowed in the PE). You can use those suggestions when you envision future versions of the product (i.e., beyond v1.4 -- to improve your product design skills. But for now, focus on fixing bugs, and perfecting other aspects such as testing, documentation, code quality.
    Also note that given there's a feature freeze in v1.4, some lower-priority features can be argued as out-of-scope if there were other higher priority features that took up the available time in previous versions. Every team has to draw the line somewhere as there wasn't a lot of time to implement features.
  • Follow the procedure for dealing with PED bugs you received:

  • Fix bugs that were reported during the PE-D. Don't rely on PE-D alone to find bugs. Also keep in mind that bug fixing can cause regressions which you'll have to catch and fix.

  • Do more extensive testing yourselves.

    • If your software has a GUI that has a large default size, ensure that it works even in lower-resolution screens (within reasonable limits). In the past, there were cases where the GUI opened up bigger than the screen with some important parts not visible, and users were unable to proceed further.

  • Update documentation to match the product. In particular, finalize the content of the DG early and check it thoroughly for bugs (reason: unlike the UG, the DG did not get tested in the PE dry run).

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

  • As before, you may split this milestone into smaller iterations if you wish e.g., v1.4, v1.4b, ...

Draft the PPP

  • Create the first version of your Project Portfolio Page (PPP).
    Reason: Each member needs to create a PPP to describe your contribution to the project.

Prepare for the demo rehearsal

Not applicable this semester

Prepare final deliverables

  • Final deliverables are due early next week. You are advised to start preparing them well in advance of the submission deadline as any deadline overruns can result in penalties.

Double-check RepoSense compatibility

  • Once again, double-check to ensure the code attributed to you by RepoSense is correct.

Do final polish-ups

  • Continue with any remaining bug fixing and test/code-quality/documentation improvements.

Submit deliverables

  • Deadline for all v1.4 submissions is Mon, Apr 12th 2359 unless stated otherwise.
  • Penalty for late submission:
    -1 mark for missing the deadline (up to 2 hour of delay).
    -2 for an extended delay (up to 24 hours late).
    Penalty for delays beyond 24 hours is determined on a case by case basis.
    • Even a one-second delay is considered late, irrespective of the reason.
    • For submissions done via LumiNUS, the submission time is the timestamp shown by LumiNUS.
    • When determining the late submission penalty, we take the latest submission even if the same exact file was submitted earlier. Do not submit the same file multiple times if you want to avoid unnecessary late submission penalties.
    • The whole team is penalized for problems in team submissions. Only the respective student is penalized for problems in individual submissions.
  • Submit to LumiNUS folder we have set up, not to your project space. cs2103T students: documents should be submitted to both modules. It's not enough to submit to CS2101 side only.
  • Follow submission instructions closely. Any non-compliance will be penalized. e.g. wrong file name/format.
    • For pdf submissions, ensure the file is usable and hyperlinks in the file are correct. Problems in documents are considered bugs too e.g. broken links, outdated diagrams/instructions etc..
  • Do not update the code during the 14 days after the deadline. Get our permission first if you need to update the code in the repo during that freeze period.
    • You can update issues/milestones/PRs even during the freeze period.
    • [CS2103T only] You can update the source code of the docs (but not functional/test code) if your CS2101 submission deadline is later than our submission deadline. However, a freeze period of 1-2 days is still recommended, so that there is a clear gap between the tP submission and subsequent docs updates.
    • You can update the code during the freeze period if the change is related to a late submission approved by us.
    • You can continue to evolve your repo after the freeze period.

Submissions:

To convert the UG/DG/PPP into PDF format, go to the generated page in your project's github.io site and use this technique to save as a pdf file. Using other techniques can result in poor quality resolution (will be considered a bug) and unnecessarily large files.

Ensure hyperlinks in the pdf files work. Your UG/DG/PPP will be evaluated using PDF files during the PE. Broken/non-working hyperlinks in the PDF files will be considered as bugs and will count against your project score. Again, use the conversion technique given above to ensure links in the PDF files work.

Try the PDF conversion early. If you do it at the last minute, you may not have time to fix any problems in the generated PDF files (such problems are more common than you think).

The icon indicates team submissions. Only one person need to submit on behalf of the team but we recommend that others help verify the submission is in order
We will not accept requests to limit late penalties of team submissions to one person even if the delay was one person's fault. That is, the responsibility (and the penalty) for team submissions are to be shared by the whole team rather than burden one person with it.

The icon indicates individual submissions. When uploading files to LumiNUS, please upload your individual files yourself. Reason: Penalties related to submission time/format are calculated automatically based on the uploader's identity.

  • Product:
    • Do a release on GitHub, tagged appropriately e.g., v1.4 or v1.4b.
    • Upload the jar file to LumiNUS.
      File name: [team ID][product name].jar e.g. [CS2103-T09-2][Contacts Plus].jar

  • Source Code: Push the code to GitHub and tag with the version number. Source code (please ensure the code reported by RepoSense as yours is correct; any updates to RepoSense config files or @@author annotations after the deadline will be considered a later submission). Note that the quality of the code attributed to you accounts for a significant component of your final score, graded individually.

  • User Guide: Convert to pdf and upload to LumiNUS.
    File name: [TEAM_ID][product Name]UG.pdf e.g.[CS2103-T09-2][Contacts Plus]UG.pdf

  • Developer Guide: submission is similar to the UG
    File name: [TEAM_ID][product Name]DG.pdf e.g. [CS2103-T09-2][Contacts Plus]DG.pdf

  • Project Portfolio Page (PPP):
    • PDF file: submission is similar to the UG
      File name: [TEAM_ID][Your full Name as Given in LumiNUS]PPP.pdf e.g.[CS2103-T09-2][Leow Wai Kit, John]PPP.pdf
      Use - in place of / if your name has it e.g., Ravi s/o Veegan → Ravi s-o Veegan (reason: Windows does not allow / in file names)
    • HTML version: make available on github.io

  • Product Website: Update website (home page,Ui.png, AboutUs.md etc.) on GitHub. Ensure the website is auto-published.

Wrap up the milestone

  • As usual, wrap up the milestone on GitHub. Note that the deadline for this is the same for everyone (i.e., does not depend on your tutorial).

Submit the demo video

Prepare for the practical exam

Attend the practical exam

  • Attend the practical test, to be done during the lecture.

5 Wrap up v1.3

  • as before

6 Demo v1.3 before the tutorial

  • [one member] As was done in v1.2,
    • Run your application using the JAR file that you released for v1.3.
    • Take screenshots of each available feature in action (or screen-record a demo -- need not be polished).
    • Add those screenshots (or upload the demo video somewhere and give the link) to your collaborative project notes document with an appropriate heading e.g., v1.3 features demo.


tP week 10: mid-v1.3tP week 12: mid-v1.4