Week 13 [Mon, Nov 11th] - Project

tP: v1.6

  1. Fix PE-D bugs
  2. Submit final deliverables Tue, Nov 12th 14:00
  3. Prepare for the practical exam
  4. Ensure the code is RepoSense-compatible
  5. Attend the practical exam Fri, Nov 15th 1600-1800
  6. [if needed] Attend the makeup practical exam Sun, Nov 17th 1400-1600

tP: Public release → v1.6

Intro to tP Week 13

What's happening this week:

v1.6

  • Learning outcome: Able to put in final touches while minimizing delivery risks i.e., risks of regressions or deadline overruns.
  • Product goal: Reach the quality necessary for a public release.
  • Strategy: Freeze features. Strictly limit changes to bug fixes only.

Things to note:

Remind yourself of our policy on reuse (e.g., how to give credit for reused code):

1 Fix PE-D bugs

High-level workflow for deciding what to do for each PE-D bug

  1. Is it something you think you'll never fix even if you were to continue this project in future?
    If yes, you can leave it unfixed and reject it if the same is reported in the PE. Caution: If the PE tester disagrees and the teaching team agrees with the tester's justification, the bug might result in a penalty (why say 'might result ...'? Because only when the bug density exceeds a certain bar that bugs will be penalised).
    How to decide if a PE bug can be rejected? Refer to PE Bug Triaging Guidelines for details (you may skip the 'General' section).
  2. Else, is it something you may consider fixing in a future version but was not important enough to do in v1.5?
    If yes, you can expect to categorise it as NotInScope if the same is reported in the PE (eligibility criteria).
  3. Else, it is something you should have fixed in the current version. Then,
    • does it qualify as bug, as defined in the feature freeze?
      If yes, you may fix it in this iteration. If left unfixed, it can be reported as a bug in PE, and might result in a penalty eventually.
    • Else, it is an enhancement that you should have done by v1.5 but overlooked.
      • As enhancements are not allowed during the feature freeze, you can list it under 'Planned Enhancements' in the DG so that it becomes immune to PE bug reporting.
      • Alternatively (or in addition), you can also update the UG to mitigate its impact on users (e.g., keep users informed of it).
  1. Triage bugs you received in the PE-D, by following the procedure given below:

  1. Note what is allowed in this milestone:

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 other words, avoiding behavior changes unless they are strictly necessary, so that we minimize the possibility of introducing more bugs.
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.6 should not have any behaviors that were not already tested in the ). Hence, the feature freeze comes into effect at the point you released the JAR file that was used for the PE-D.

While the info below provides you what to do and what not to do in v1.6 specific cases, the important thing is to understand and follow the spirit of the feature freeze (i.e., do not change features further; correct unintentional errors only).

Allowed in the v1.6 milestone:

  • fixing bugs (but not feature flaws) -- we use a very restrictive definition of 'bugs' for the feature freeze; to avoid violating the feature freeze unintentionally, be sure to check the FAQs below before you do any fixes/tweaks.
  • improving documentation (e.g., update UG, DG, code comments)
  • code quality improvements (e.g., fixing coding standard violations, adding assertions/logging)-- we advise against major refactorings though, as it defeats the purpose of the feature freeze (which aims to minimize the risk of introducing bugs)
  • improving the testing aspect (e.g., add more tests)
  • removing features (i.e., removing an entire feature or a part of a feature)

Not allowed in v1.6:

  • adding/changing features (even minor behavior enhancements/tweaks)
  • any UI enhancements (even purely cosmetic enhancements e.g., alignments, style changes are not allowed)
  • updates to the contents of data files bundled with the JAR file (as they control the behavior of the app)

Using 'Planned Enhancements' DG section to counter known feature flaws: Given you are not allowed to fix feature flaws in v1.6, we allow you to optionally add a section named Appendix: Planned Enhancements to the end of the DG. More details in the panel below:

FAQs on what is allowed during the feature freeze:

[Q0] What's the penalty for violating the feature freeze?

[Q1] How to differentiate between bugs vs enhancements?

[Q2] Will we be penalized for feature flaws not fixed during the feature freeze?

[Q3] What if an issue is related to a behavior not specifically stated in the UG?

[Q4] What if a feature is mentioned in the UG but not available fully in the product?

[Q5] Can we tweak validity checks for a user input, or error/exception handling?

[Q6] Can we tweak UI text (i.e., error/help messages or other text shown to the user)?

[Q7] Can we tweak case-sensitivity of a feature?

[Q8] A UI text gets truncated (or overflows) for certain inputs (or certain Windows sizes); can we fix them?

[Q9] Can we tweak the command format?

[Q10] What if the UI is inconsistent with the data?

[Q11] The tester has categorized a PE-D issue as a feature-flaw but we think it is a bug (or vice versa). How to proceed?

[Q12] We already merged a PR that violates the feature freeze. Now what?

[Q13] How to decide between recording a feature flaw as a 'known issue' (in the UG) and a 'planned enhancement' (in the DG)?

[Q14] What if the the current behavior X is reported as a bug in the PE? Will it be considered a bug?

  1. Fix bugs that you deem as important enough to be fixed in v1.6. Also keep in mind that bug fixing can cause regressions which you'll have to catch and fix.
    Look for more bugs, and fix them too (i.e., don't limit to bugs found in the PE-D only).

  2. Submit peer evaluations for PE-D testers: Submit your peer-evaluation of PE-D testers to indicate how well they helped your team.
    Deadline: by Wed, Nov 13th 2359
    The submission is to be done via the TEAMMATES system.
    Only one team member needs to submit on behalf of the team but discuss among team members first.
    Base the evaluation on the quality/usefulness of the bugs reported as well as the quantity.
    Here are the two questions you'll need to answer in the evaluation:

PE-D bug titles will be prefixed with tester ID e.g., ([PE-D][Tester A] UG does not load) to make it easy for you to bugs reported by each tester.
Furthermore, tester ID mapping (i.e., who is Tester A, Tester B, etc.) will be sent to you via email within 1 day after the PE-D.

2 Submit final deliverables Tue, Nov 12th 14:00

  • Deadline for all v1.6 submissions is Tue, Nov 12th 14:00:00 unless stated otherwise. Note that 14:00:01 is considered late, as per the Canvas deadline mechanism.
  • Penalty for late submission (per file):
    -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 Canvas, the submission time is the timestamp shown by Canvas.
    • 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 e.g., a -1 penalty for a team submission will be a -1 penalty for each team member.
  • Submit via the Canvas assignment we have set up. CS2103T students: documents should be submitted to both courses. 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.
    Canvas might automatically add a file name suffix (e.g., *-1.pdf, *-2.pdf, ...) if you upload a file multiple times. You can safely ignore that suffix.
  • 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 code-freeze period.
    • You can update issues/milestones/PRs even during the code-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 code-freeze period of 1-2 days is still recommended, so that there is a clear gap between the tP submission and subsequent docs updates.
      On a related note, there is no need to additional stylistic 'beautifications' to the docs before submitting to CS2101 side. The two teaching teams have agreed that there will be no extra credit for such additional beautifications.
    • You can update the code during the code-freeze period if the change is related to a late submission approved by us.
    • You can continue to evolve your repo after the code-freeze period.

Submissions:

Don't take PDF conversion lightly: To convert the UG/DG 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 or not following the settings suggested in the given technique can result in issues such as missing background colors, poor quality resolution, unnecessarily large files (the last two can be considered as bugs).

The PDF versions of the UG/DG should be usable by the target readers, even if not as neat/optimized as the Web versions. For example, margins and page breaks need not be optimized, but they should not hinder the reader either. Assume some will occasionally choose the PDF version over the Web version e.g, for printing, offline viewing, annotating etc.

PE uses the PDF versions of UG/DG, not the Web version! Any problems in those PDF files (e.g., broken links, messed up formatting) can be reported as bugs.

Ensure hyperlinks in the pdf files work. Broken/non-working hyperlinks in the PDF files will be considered as bugs. Again, use the conversion technique given above to ensure links in the PDF files work.

PDF files should,

  • be paginated at a reasonable page size (e.g., A4). Reason: single-page PDF files don't work well in some PDF viewers, and not suitable for printing either.
  • allow copying text so that readers can copy text from them (e.g., copy an example command from the UG).

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

Side benefits for early submissions: Given that using buffers to reduce the risk of deadline overruns is a learning outcome of this course, we strongly encourage setting an internal submission deadline a few hours earlier than the actual deadline. As an incentive, we plan to perform some checks on early submissions and inform you if we found issues with your submission (e.g., incorrect file name/format), thus giving you a chance to fix them before the deadline and avoid a penalty for it.

You may use automated tools to improve documentation: e.g., tools such as Grammarly may be used to improve the writing quality and find grammar errors.

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

  • Product:
    • Do a release on GitHub, tagged appropriately e.g., v1.6 or v1.6b.
      Writing detailed release notes is optional.
      No need to include UG/DG pdf files in the release.
    • Upload the jar file to Canvas.
      File name: [team ID][ProductName].jar e.g. [CS2103-T09-2][ContactsPlus].jar
      Recommended to avoid spaces and special characters in the product name as it can cause problems when running the JAR file using the command line.
      This name requirement is for the JAR file you upload to Canvas only. You may name the JAR file you upload to GitHub in any reasonable way.

  • Source Code: Push the code to GitHub and tag with the version number.

Reminder: double-check to ensure the code attributed to you by RepoSense is correct.

  • User Guide:
    • Convert to pdf and upload to Canvas.
    • File name: [TEAM_ID][ProductName]UG.pdf e.g.[CS2103-T09-2][ContactsPlus]UG.pdf

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

  • [Optional] Project Portfolio Page (PPP):
    • HTML version: make available on github.io
    • See the panel below to learn when you should opt for this submission.

Admin tP → Deliverables → Project Portfolio Page

At the end of the project each student is required to submit a Project Portfolio Page. To reduce workload, this deliverable has been made optional this semester. You need to submit this only if you think your team members are not fully aware of your contribution to the tP. Also, we will ask you to submit this if there is a dispute about your contribution level.

Details ... (read only if you opted to submit this deliverable)

PPP Objectives

  • For you to use (e.g. in your resume) as a well-documented data point of your SE experience
  • For evaluators to use as a data point for evaluating your project contributions

PPP Sections to include

  • Overview: A short overview of your product to provide some context to the reader. The opening 1-2 sentences may be reused by all team members. If your product overview extends beyond 1-2 sentences, the remainder should be written by yourself.
  • Summary of Contributions --Suggested items to include:
    • Code contributed: Give a link to your code on tP Code Dashboard. The link is available in the Project List Page -- linked to the icon under your profile picture.
    • Enhancements implemented: A summary of the enhancements you implemented.
    • Contributions to the UG: Which sections did you contribute to the UG?
    • Contributions to the DG: Which sections did you contribute to the DG? Which UML diagrams did you add/updated?
    • Contributions to team-based tasks
    • Review/mentoring contributions: Links to PRs reviewed, instances of helping team members in other ways.
    • Contributions beyond the project team:
      • Evidence of helping others e.g. responses you posted in our forum, bugs you reported in other team's products,
      • Evidence of technical leadership e.g. sharing useful information in the forum

Keep in mind that evaluators will use the PPP to estimate your project effort. We recommend that you mention things that will earn you a fair score e.g., explain how deep the enhancement is, why it is complete, how hard it was to implement etc.

  • OPTIONAL Contributions to the Developer Guide (Extracts): Reproduce the parts in the Developer Guide that you wrote. Alternatively, you can show the various diagrams you contributed.
  • OPTIONAL Contributions to the User Guide (Extracts): Reproduce the parts in the User Guide that you wrote.

PPP Format

  • File name (i.e., in the repo): docs/team/github_username_in_lower_case.md e.g., docs/team/goodcoder123.md
  • Follow the example in the AddressBook-Level3
  • PDF file submission: not required.

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

3 Prepare for the practical exam

  • After reading the above 2, we strongly recommend you read ahead the info given in the item 5 below as well, to know in advance what will happen during the PE itself.

4 Ensure the code is RepoSense-compatible

  • Ensure your code is 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:

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

5 Attend the practical exam Fri, Nov 15th 1600-1800

  • Ensure you read the instructions on PE Preparation (given in item 5 above)
  • Attend the practical test, to be done during the weekly briefing.

6 [if needed] Attend the makeup practical exam Sun, Nov 17th 1400-1600

  • In the very unlikely event that the PE had to be cancelled due to technical issues, attend the makeup PE on this day.
  • Note: This is not an alternative option for students who could not attend the PE, as all students need to do the PE at the same time.