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

Week 7 [Fri, Sep 22nd] - Project

iP:

  1. [Optional] Get more out of the iP

tP: v1.1

  1. Do a practice iteration midnight before the tutorial
  2. Update project website: AboutUs, README
  3. Update the UG
  4. Add a skeletal PPP
  5. Update the DG: user stories, glossary, NFRs, use cases
  6. Plan the next iteration
  7. Start implementing the next version

iP

1 [Optional] Get more out of the iP

If you wish to cite the iP in your resume, you can do more to make it look more impressive to a potential employer. These improvements are not considered for grading and can be done after the semester is over. Some ideas:

  • Improve the GUI: Make the UI look nicer, unique, and memorable. You can get inspiration from what others have done (but remember to give credit if you reuse any code from them).
  • Add a demo video or an animated gif to your user guide to show how the app works.
  • Improve code quality: iP is the right size to cite as an example of your code quality. You can use the RepoSense link (</>) in the iP showcase page to point to your iP code.
  • Add more features.

On a somewhat related note, you can also create similar product websites for your other projects (projects from other courses, pet projects).

tP: Get ready for iterations


Start using Git via the CLI

If you have been using Sourcetree (or other GUI) for Git before, we strongly recommend that you move towards using the CLI to perform Git tasks in the second half of the semester. Doing so will strengthen your Git knowledge (because CLI takes you closer to what's actually happening, while GUIs might hide such details).
But you can continue to use your favorite Git GUI for a more 'visual' view of your repo, side-by-side with the CLI e.g., from Sourcetree, you can open a gitbash terminal, run the command in that terminal, and see the result in the GUI.

PR review comments matter! Remember to do proper PR reviews throughout the tP, at least for non-trivial changes, as the quality and quantity of PR review comments you have given to peers affect your tP marks (under the project management aspect).

1 Do a practice iteration midnight before the tutorial

  • To get some practice of doing project iterations, do this week's tP work (which is just updates to various documents, no changes to functionality) to reach the milestone v1.1. The panel below explains how to use GitHub to do a project iteration.

Strongly recommended to do this as a team activity (preferably F2F, or else connected via Zoom/MST), at least until everyone has merged a few PRs for this iteration. That will help you proceed faster (e.g., a PR can be reviewed immediately after it has been created) and will also make it easy for you to help each other w.r.t. to the workflow matters.

  • The documentation updates to be done in this iteration are described in the tP tasks in the sections below.
  • Don't forget to 'wrap up' the milestone (as explained in the panel above), after the work is done.
  • Ideally, this should be done by the midnight before the tutorial, but failing that, before the next lecture, as usual.

2 Update project website: AboutUs, README

Recommended procedure for updating docs:

  1. Divide among yourselves who will update which parts of the document(s).
  2. Update the team repo by following the workflow given below:

How to go about editing documentation files?
e.g., How to preview changes locally before committing/pushing?

Guidance on documentation can be found in the relevant section of the Developer Guide of your team project website that you set up earlier. Given below is a shortcut, for your convenience:

Lookout for these mistakes which were the most common in previous runs of the course:

  1. Not following the required phrasing style for the first sentence of Java method header comments.
  2. Not following the convention for Git commit message subject.
    Caution: This is very hard to rectify later, after PR containing the commits have been merged.
    Reason: While Git allows editing past commits, it changes their timestamp, which affects your weekly code contribution stats (which are factored into evaluating the consistency of your coding work over the project duration)

A: Update the following pages in your project repo:

  • AboutUs page: This page (in the /docs folder) is used for course admin purposes. Please follow the format closely or else our scripts will not be able to give credit for your work.
    • Add your own details. Include a suitable photo as described here.
    • There is no need to mention the tutor/lecturer, but OK to do so too.
    • The filename of the profile photo should be docs/images/github_username_in_lower_case.png
      Note the need for lower case ( ) e.g. JohnDoe123 -> docs/images/johndoe123.png not docs/images/JohnDoe123.png.
      If your photo is in jpg format, name the file as .png anyway.
    • Indicate the different roles played and responsibilities held by each team member. You can reassign these roles and responsibilities (as explained in Admin Project Scope) later in the project, if necessary.

  • README page: Update it to match your project.

    • Add a UI mockup of your intended final product. Note that the image of the UI should be docs/images/Ui.png so that it can be downloaded by our scripts. Limit the file to contain one screenshot/mockup only and ensure the new image is roughly the same height x width proportions as the original one. Reason: when we compile these images from all teams into one page (example), yours should not look out of place.
      If you did the above update correctly, UI mock up and profile photos should appear in your project website and this Project List Page.
      The UI mock up can be a hand-drawn sketch or created using a tool such as PowerPoint, PlantUML, Figma, etc.
      Can the AB3 screenshot used for this? Only in the unlikely case that your v1.2 UI looks exactly the same as AB3.

    • Update all contents to match your own project.

    • Update the link of the GitHub Actions build status badge (Build Status) so that it reflects the build status of your team repo.

    • Acknowledge the original source of the code e.g.,
      This project is based on the AddressBook-Level3 project created by the [SE-EDU initiative](https://se-education.org).

B: Also update site-wide settings, as necessary:

  • You need to update the AB-3 in the top navigation bar of your project website (it's in docs\_sass\minima\_base.scss if using Jekyll, and in docs\_markbind\layouts\default.md if using MarkBind).

  • More info on updating site-wide settings such as the above:

3 Update the UG

  • Move the draft UG content into the User Guide page in your repository. Update the content/structure/formatting as necessary, to match the final form of the UG. If a feature is not implemented in the current version, you can either omit it from the UG or mark it as 'Coming soon' (e.g., ## Archiving contacts [coming soon]).
    Remember to omit nitty-gritty details in the previous 'internal' UG Draft if they are not appropriate for the actual UG.
    As mentioned before, while it is more convenient for one person to update the entire UG, we recommend that each person updates their own part of the docs so that we can easily track the contribution of each member using RepoSense.

4 Add a skeletal PPP

At the end of the project, each member needs to create a Project Portfolio Page (PPP) to describe your contribution to the project. Let's create a skeletal version of the PPP now itself so that everyone becomes aware how detailed you need to be about your individual contributions at the end of the project.

  • Create a skeletal version of your Project Portfolio Page (PPP).
    • Just the headings are enough. You can write to be added soon as placeholders for content.
    • PDF conversion not required.
    • Follow the details in the panel below.

5 Update the DG: user stories, glossary, NFRs, use cases

  • Add the following to the DG, based on your project notes from the previous weeks.
    Some examples of these can be found in the AB3 Developer Guide.

    • Target user profile, value proposition, and user stories: Update the target user profile and value proposition to match the project direction you have selected. Give a list of the user stories (and update/delete existing ones, if applicable), including priorities. This can include user stories considered but will not be included in the final product.
    • Use cases: Give use cases (textual form) for a few representative user stories that need multiple steps to complete. e.g. Adding a tag to a person (assume the user needs to find the person first)
    • Non-functional requirements: Note: Many of the given project constraints can be considered NFRs. You can add more. e.g. performance requirements, usability requirements, scalability requirements, etc.
    • Glossary: Define terms that are worth recording.

The above DG sections should cover the full requirements of the product, some of which might not even get implemented by the end of this semester i.e., do not limit to just the requirements you intend to implement in the next iteration. Reason: All identified requirements need to be documented for future reference.

Furthermore, these sections will be graded at the final project evaluation, and any bugs in the content can cost you marks at that point. The panel below gives some relevant DG bug examples you can lookout for:

6 Plan the next iteration

  • Plan the next iteration. As you know, you should follow the breadth-first iterative process. Therefore, first you must decide what functionalities should be in the product if you had only two weeks to implement it. You have done that already when you chose user stories for v1.2, translated that to features, and even drafted the UG based on those features. You can tweak that plan further at this point if you wish, given that you now have some idea of how fast the team can work when using the prescribed workflow.
    • Aim to produce a working MVP at the end of this iteration even if the functionalities are not polished (polishing can be done in a later iteration).
    • Avoid depth-first implementations: "I'll do the back-end part of feature X in this iteration" is not acceptable as that is not in the spirit of breadth-first iterative process. Remember, we are pretending this to be the last iteration; why would you implement the back-end part of a feature in the last iteration?
      It is OK to add simpler versions of bigger features, but not OK to add partial features that can't be used yet.
    • [Recommended, Optional] Break the iteration into two mini iterations as follows:

Splitting v1.2 into two mini iterations

  • v1.2: the first working version of your product, to be delivered by the mid-milestone (i.e., in about one week). As this is an internal milestone, the exact deadline is upto your team.
  • v1.2b: an even more functional version of the product, to be delivered by the end of the full iteration (i.e., in two weeks)

This goal of this 'optimization' is to reduce the risk of an . As a side benefit, it also gives you more opportunities to practice iteration planning.

The reason for naming the earlier milestone as v1.2 is so that even if you fail to finish the second one, you can still get credit for reaching v1.2 (which is the milestone tracked by grading scripts) -- think of the first iteration as minimal deliverables for v1.2 and the second one as containing do-if-there-is-time improvements.

Each mini iteration should deliver a working product, not just do half of the tasks planned for the full iteration. Otherwise, it defeats the purpose of this optimization.

  • Divide the work among the team members i.e., the work required for the current iteration.
  • Reflect the above plan in the issue tracker by assigning the corresponding issues (create new issues if necessary) to yourself and to the corresponding milestone. For example, the user story pertaining to the increment show a placeholder for photo, showing a generic default image should be assigned to Jake and to milestone v1.2

7 Start implementing the next version

  • If you have time, start implementing v1.2.