Week 12 [Mon, Nov 2nd] - Project

tP: v1.6

  1. Fix any latent bugs
  2. Submit final deliverables Tue, Nov 3rd 14:00
  3. Prepare for the practical exam
  4. Take part in the practical exam (PE) Fri, Nov 6th 12 noon to Sat, Nov 7th 12 noon

tP: Public Release → v1.6

Intro to tP Week 12

What's happening this week:

v1.6

  • Learning outcome: Able to put in the final touches while minimizing delivery risks i.e., regressions or deadline overruns.
  • Product goal: Reach the quality necessary for a public release.
  • Strategy: Freeze features. Avoid code changes unless strictly necessary.

Things to note:

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

1 Fix any latent bugs

Find any bugs that slipped through alpha testing.

  1. Note the following details of the feature freeze enforced in this iteration:

The goal of freezing features in the pre-release iteration is to minimize latent bugs by avoiding behavior changes unless they are strictly necessary.
In a real project, minor or critical changes might be allowed even near a deadline -- but in the tP, it is hard to enforce such a rule objectively. Instead, we use a quantitative limit that is easier to enforce: no more than 15% or 100 LoC (whichever is higher) of the functional code is allowed to be changed during iteration v1.6.
Finer details of this limit are given below (also see [Q0] and [Q1] given under FAQs):

  • The feature freeze starts at the v1.5 deadline (Thu 23:59). Any code updated after that time is counted against the feature freeze.
  • The limit is applied per member. That is, we compare the amount of code attributed to each member (as per the tP code dashboard) against the portion of that code that was changed during the feature freeze. Any penalty for violating the feature freeze will be applied to that member only.
  • The limit applies to functional code only. More specifically, it covers all changes (including blank lines and comments) to any code file inside the src\main folder and sub-folders. The feature freeze doesn't apply to test code, documentation, or non-code files (e.g., images).
  • The calculation is based on the tP code dashboard, computed as 'of the total functional LoC attributed to you at the end of v1.6, what percentage was edited by you during the feature freeze?'.
  • The penalty for violating the feature freeze will be decided on a case-by-case basis, but not smaller than -2.
  • We will allow a 5% margin of error on top of the 15% -- so, you will not be penalized if you exceed 15% by a tiny bit (i.e., up to 20%).
  • There is no limit on the nature of changes you can make to functional code, but we strongly recommend choosing based on:
    a) the priority (i.e., how important the change is), and
    b) the risk (i.e., the chance of the change introducing new bugs).

Using the 'Planned Enhancements' DG section to counter known feature flaws: Given you are not allowed to update functional code freely 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 the feature freeze:

[Q0] How exactly is the LoC limit calculated?

[Q1] How can a student calculate/track how much code s/he can change?

[Q2] Suppose fixing a bug will violate the feature freeze but not fixing it can incur a penalty during the PE. How do we decide which option is less costly?

[Q3] Is minor/cosmetic code refactoring counted against the feature freeze?

[Q4] Change percentage is counted using all lines or non-blank lines only?

[Q5] Can we squeeze more changes into the feature freeze by 'clever hacks' (e.g., combining multiple lines, etc.)?

[Q6] Can I borrow the unused 'change quota' of another member?

[Q7] Can we add entirely new features during the feature freeze?

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

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

  1. Fix bugs that you deem 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.

High-level workflow for deciding which bugs to fix during feature freeze

  1. Is it something you think you'll never fix even if you were to continue this project in the future?
    If yes, you can leave it unfixed and reject it if the same bug 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 bugs are penalized only when the bug density exceeds a certain bar).
    How to decide if a PE bug can be not-accepted? 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 that was not important enough to have been done in v1.5?
    If yes, you can expect to categorize it as NotInScope if the same bug is reported in the PE (eligibility criteria).
  3. Else, it is something you should have fixed in the current version.
    • You may fix it in this iteration. If left unfixed, it can be reported as a bug in the PE, and might result in a penalty eventually.
    • Alternatively, you can list it under 'Planned Enhancements' in the DG so that it becomes immune to PE bug reporting (caution: there is a limit on how many items you can list as planned enhancements -- see the panel below for more details).
      In addition, you can update the UG to mitigate its impact on users (e.g., keep users informed of it).

FAQ How to choose between feature design choices?

2 Submit final deliverables Tue, Nov 3rd 14:00

  • Deadline for all v1.6 submissions is Tue, Nov 3rd 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 hours late).
    -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 exact same 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 the 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.jar, *-2.jar, ...) if you upload a file multiple times. You can safely ignore that suffix.
  • Do not update the code during the 30 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.
    • 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:

The icon indicates team submissions. Only one person needs 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 is to be shared by the whole team rather than borne by one person.

Your team ID:
Your product name:
Note: Type your team ID and product name in the fields above so that we can customize the content below to fit you.

  • Product:
    • Do a release on GitHub, tagged appropriately e.g., v1.6 or v1.6b.
      Writing detailed release notes is optional.
    • Upload the JAR file to Canvas.
      File name: [TEAM_ID][ProductName].jar e.g., [[[teamId: CS2103T-T09-2]]][[[productName: ContactsPro]]].jar
      Recommended to avoid spaces and special characters in the product name as they 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 it with the version number.

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

  • User Guide:
    • Ensure the updated version is available as part of your product website deployed on GitHub Pages.

  • Developer Guide:
    • submission is similar to that of the UG

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

  • 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

Deliverable: Project Portfolio Page (PPP)

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, you should write the remainder 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/update?
    • 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 teams' 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.

3 Prepare for the practical exam

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

4 Take part in the practical exam (PE) Fri, Nov 6th 12 noon to Sat, Nov 7th 12 noon

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