Week 10 [Mon, Oct 19th] - Project

tP: v1.4

  1. Do a postmortem of the previous iteration before the tutorial
  2. Plan the alpha version (v1.4)
  3. Deliver the alpha version (v1.4) Thu, Oct 22nd 23:59
  4. Start updating UML diagrams in the DG

tP: Alpha Version → v1.4

Intro to tP Week 10

What's happening this week:

v1.4

  • Learning outcome: Able to tweak the product/project plan to match the available time/resources.
  • Product goal: Implement versions of all the features intended for final release.
  • Strategy: Add features based on priority, while maintaining a working product. It is OK if the features are rough around the edges, as they can be tweaked in the next iteration.

In this iteration, we learn from past iterations, and aim to plan better and deliver another functional increment that would get you very close to the final version in terms of raw functionality.
We call this the alpha version because this version is meant to be good enough for of the product.

First, in task 1 we look back at the previous iteration, to see what we can learn from it.
Then, in task 2 we plan features to implement in this version, while aiming to come very close to the final product's feature set.
Finally, in task 3 we implement those features to deliver v1.4.

Things to note:

FAQ How much code/features is enough to get full marks?

Heads up: this is a BIG week of the tP!

Ideally, the tP work should be distributed equally across all tP weeks. In practice, though, this can be uneven based on your other commitments -- e.g., most did less work in weeks 7-8 due to midterm exams.

If you were to pick one tP week to push the hardest, this week should be it! That is because in this iteration you need to implement all features that you plan to include in the final version (but they need not be fully polished).

1 Do a postmortem of the previous iteration before the tutorial

  • Discuss with the team how the iteration went (i.e., what worked well, what didn't), and your plans to improve the process (not the product) in the next iteration.
  • Submission: Keep notes about the discussion in your shared project notes document so that the tutor can check them later.

Wish to simplify the PR workflow? If you are now comfortable with the forking workflow and would like to practice a simpler one, you can bypass your fork and push branches to the team repo from now on. You should still create PRs from those branches before merging them though.

2 Plan the alpha version (v1.4)

The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time.

--Tom Cargill, Bell Labs

  • Decide the scope: Start by identifying what features you would include in the final product if you had only one more week to deliver them. In this iteration, aim to deliver at least a version of those features.
    🤔 What's the hurry to add all features right now? We will be enforcing a strict feature freeze at the end of v1.5 (more details in the panel below). Given you also need time to polish the features before the feature freeze starts (during which code changes will be severely restricted), it makes sense to finish the bulk of the feature implementation in this iteration (v1.4), so that you have time to test and polish it in v1.5.

Admin tP → v1.6 (extract) → More details on the feature freeze

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

  • Plan the iteration: Decide the order/timeline for those features, record that plan using issues, and assign team members to those issues. Plan tasks based on priority, while staying breadth-first.

3 Deliver the alpha version (v1.4) Thu, Oct 22nd 23:59

Caution: Be wary of auto-sizing app windows.
  • Follow the iteration plan you devised above to deliver the features.
    Resist the temptation to try to deliver each of those features/enhancements in one PR. It is better to deliver a minimal version first, and improve it through subsequent PRs.
  • Manage the iteration better than the previous iteration (hopefully), as per what you learned/decided during the v1.3 postmortem.
  • Release v1.4. Include a JAR file and detailed release notes (as before, the release notes should describe what is new since the last release).
Ways to level up your tP game:
  1. Use parallel PRs: We encourage you to try sending parallel PRs (i.e., send another PR while the previous PR you sent is waiting to be merged) if you haven't done that yet.
    Reason: It's important to learn how to do that, because in most real projects it is common to have multiple open PRs from the same author.
    We require each student to have parallel PRs at least once during the tP so that we can confirm you are able to handle them.
  2. Maintain the defensiveness of the code: Use assertions, exceptions, and logging in your code, as well as other defensive programming measures (refer to this week's topic on defensive programming for more details) when appropriate. This will be considered when grading your tP code quality.
    Remember to enable assertions in your IDEA run configurations and in the gradle file.

FAQ How to choose between feature design choices?

FAQ How much code/features is enough to get full marks?

Some other relevant FAQs, repeated from last week:

FAQ Should we try to automate GUI testing as well?

FAQ All tests pass locally, but the same code fails CI in the PR. How come?

FAQ PR passed CI before merging, but fails CI after merging. How come?

FAQ PR CI fails because Codecov reports a drop in code coverage. What to do?

FAQ Are we allowed to deviate from the MVP Feature Specification submitted earlier?

4 Start updating UML diagrams in the DG

This is a good time to get familiar with the diagramming tools used by the tP.

  • Each member is recommended to update at least one UML diagram in the DG, to match the changes you've made so far in v1.4. You may do this toward the end of v1.4, or soon after you finish it.
  • Deadline: This is not part of v1.4. So, you can do this even after you are done with the v1.4 release that is due Thursday 23:59.
    As this is a regular weekly task, the usual deadline applies, i.e., Friday 1600, and as usual, if you miss the deadline, catching up within a few days will still turn it green.
  • Updating the DG text to match the diagrams is optional (it can be done later).
  • FYI, the panel below has some DG tips, some of which are related to drawing diagrams.

FAQ Why not wait till the end to add/update the DG diagrams?

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

FAQ What if the features I added don't affect UML diagrams?

End of tP Week 10

Have any suggestions to improve AB3?

Now that you have worked with the AB3 codebase for a while, if you have any suggestions on how to improve AB3 (for future batches), feel free to post/discuss them in the forum.
Examples: places where the design/code can be simplified, hard-to-understand parts of the code, tips you can share with future batches, ...