CS2103/T - Admin: tP Week 10: Alpha Version → v1.4

Do a postmortem of the previous iteration before the tutorial
Plan the alpha version (v1.4)
Deliver the alpha version (v1.4) Thu, Mar 27th 23:59
Smoke-test CATcher [COMPULSORY] Fri, Mar 28th 16:00
Start updating UML diagrams in the DG

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 better plan and better deliver another functional increment that would get you very 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 2 we plan features to be implemented in this version, while aiming to come very close to the final product's feature set.
Finally, in 3 we implement those features to deliver the 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 works. In practice though, this can be uneven based on your other commitments e.g., most did less work in week 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.

Like to try a new Git workflow? If you feel you are now comfortable with the forking workflow, and now you would like to practice another one, your team can choose to follow the feature branch workflow from now on.

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 deciding 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, 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 in the tP, it is hard to enforce such a rule objectively. Instead, we enforce a quantitative limit that is easier to enforce: no more than 10% or 50 LoC (whichever is higher) of the functional code is allowed to be changed during the iteration v1.6.
Finer details of this limit are given below (also see [Q0] and [Q1] given under FAQs):

The feature freeze starts at 10am on the PE-D day. Any code updated after that deadlines 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 i.e., changes to files 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, 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 case-by-case basis, but not smaller than -2.
We will allow 2% a margin-of-error on top of the 10% -- so, you will not be penalised if you exceed 10% by a tiny bit (i.e., up to 12%).
There is no limit on the nature of changes you can do to functional code, but we strongly recommend to choose based on,
a) the priority (i.e., how important the change is), and,
b) the risk (i.e., the risk of the change introducing new bugs).

Using '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] Are 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 in 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, Mar 27th 23:59

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's-new-since-the-last-release-note).

Ways to level up your tP game:

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 parallel PRs.
Maintain the defensiveness of the code: Use assertions, exceptions, and logging in your code, as well as other defensive programming measures (refer 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?

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 Smoke-test CATcher [COMPULSORY] Fri, Mar 28th 16:00

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

Some background: As you know, our includes peer-testing tP products under exam conditions. At the beginning, 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 that we'll be using for the PE. We still use GitHub to record bugs reported in the PE but CATcher acts as a layer between you and GitHub, to ensure the bugs you report meet PE requirements.

This week, we would like you to smoke-test the CATcher app to ensure it can work with your OS, Browser, GitHub account, by following the steps given in the panel below.

Steps for smoke-testing CATcher:

Go to the CATcher Web version at https://catcher-org.github.io/CATcher/ using the same computer (i.e., not a mobile device) that you plan to use for the practical exam.
- Use a common browser such as Chrome, Edge, Firefox, Safari
- Allow popups from https://catcher-org.github.io/
- If you encounter other problems at the app launch, refer to the Notes on using CATcher.
Login: Choose the session CS2103/T Smoke Test, and submit.
In the next screen, login to CATcher using your GitHub account.
If the app asks for public repo access permissions, grant it (just go with the default settings).
Let CATcher create a repo named catcher-smoke-test in your GitHub account, when it asks for permission. That repo will be used to hold the bug reports you will create in this testing session.
Use CATcher (not the GitHub Web/Mobile interface) to create 1-2 . The steps are similar to how you would enter bug reports in the GitHub issue tracker. Include at least one screenshot in one of those bug reports.
you can copy-paste screenshots into the bug description.
You can use Markdown syntax in the bug descriptions.
The severity and type labels are compulsory.
If you encounter any problems while using CATcher, report them at the CATcher issue tracker.
Do NOT delete the catcher-smoke-test repo created by CATcher in your GitHub account (keep it until the end of the semester) as our scripts will look for it later to check if you have done this activity.

5 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 done so far in v1.4. You may do this towards 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 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, ...

tP Week 10: Alpha Version → v1.4