Week 7 [Mon, Sep 28th] - Project

iP:

  1. [Optional] Add AI features to the iP
  2. [Optional] Get more out of the iP

tP: v1.1

  1. Do a 'workflow practice' session Thu, Oct 1st 23:59
  2. Update the README.md and site-wide settings
  3. Update the DG: user stories, glossary, NFRs, use cases
  4. Start the next iteration

iP

1 [Optional] Add AI features to the iP

Interested in adding AI features to the iP? Example:

User: @ai is there a command to add priorities to tasks?

App: Currently, there is no built-in command to add priorities to tasks.

You can follow the SE-EDU guide Adding AI Features to a Java App to learn how to do that.

Recommended: Add this feature in a separate branch, just to explore how far you can go. If you reach a version of this feature that is good enough for users (e.g., the app can still be used even if the user does not have an API key for the LLM), feel free to merge the feature and release a new JAR for the iP. In that case, remember to update the user guide on how to configure and use this feature.

2 [Optional] Get more out of the iP

If you want to cite the iP on your resume, you can make it more compelling to potential employers. These improvements are not considered for grading and can be done after the semester ends. Some ideas:

  • Improve the GUI: Make the UI look nicer, more distinctive, 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: The 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, such as those from other courses or pet projects.

tP: Practice Iteration → v1.1

Intro to tP Week 7

What's happening this week:

This week, we do the first tP iteration: v1.1.

Each tP iteration focuses on a specific learning outcome, a corresponding product goal, and a strategy that we'll use to achieve both. The ones for this tP iteration (i.e., v1.1) are given below:

v1.1

  • Learning outcome: Able to follow the workflow as a team.
  • Product goal: Update some documents to match the new product direction.
  • Strategy: Practice the workflow while updating the documents.

Aim to do 'just enough': Note how the Product goal (together with the Strategy) is simply a means to achieve the Learning outcome. Unlike in a real SE project, the product in the tP exists only to help you achieve the learning outcome. Hence, aim to do 'just enough' work on the product to achieve the intended learning outcome of the iteration (e.g., don't make features bigger than needed) so that the tP doesn't increase your workload more than necessary.

We consider this iteration a 'practice' iteration. Reason: As this is the first time your team is working on this codebase, we first focus on learning the workflow that you need to follow as a team. In this practice iteration, we limit ourselves to document updates only (to minimize the risk of breaking the codebase).

Specifically, we start with a workflow practice session (in task 1), and then do further documentation updates in tasks 2 and 3.

Things to note:

FAQ What's the deadline for tP iterations?

FAQ What if we overshoot the deadline for a tP iteration?

FAQ What should be in v1.1? Just task 1 or all three tasks?

COMMON MISTAKE: Not following the convention for Git commit message subjects.
Caution: This is very hard to rectify later, after the PR containing the commits has been merged. Reason: While Git allows editing past commits, doing so changes their timestamps, which affects your weekly code contribution stats (which are factored into evaluating the consistency of your coding work over the project duration).

COMMON MISTAKE: Forgetting to create each PR from a separate branch of your fork (i.e., sending the PR from the master branch). This error means your PR will not be considered as following the forking workflow correctly.

Start using Git via the CLI

If you have been using Sourcetree (or another GUI) for Git, we strongly recommend that you move toward using the CLI to perform Git tasks in the second half of the semester. Doing so will strengthen your Git knowledge (because the 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. For example, from Sourcetree, you can open a Git Bash terminal, run the command in that terminal, and see the result in the GUI.

1 Do a 'workflow practice' session Thu, Oct 1st 23:59

Task: Do a 'workflow practice' session to familiarize all team members with the workflow you need to follow in the tP.

Why?: The ability to modify a team-owned codebase in parallel is an important learning outcome of this course. Following a suitable workflow is critical for achieving that. This practice iteration is for you to get used to the workflow that you need to follow in the tP.

Strongly recommended to do this as a team activity (preferably F2F, or else connected via Zoom/MS Teams). That will help you proceed faster (e.g., a PR can be merged soon after it has been created) and will also make it easy for you to help each other with workflow matters.

Steps:

  1. [one member] Set up the issue tracker of your team repo, if you haven't done so already.
    In addition, create a milestone named v1.1 and set an appropriate deadline (i.e., the same as, or earlier than, the iteration deadline).

  1. [each member] Fork and clone the team repo, if you haven't done so already.

  1. [each member] Add your photo to the repo while following the prescribed tP workflow. Here are the steps (yes, it is a lot of steps for such a small update, but the purpose is to learn the workflow):
  • Read the 'tP Project Schedule Tracking' overview given below.

  • Create an issue to represent the task at hand, e.g., Add Jake's photo.

  • Assign the issue to yourself, to indicate you are taking responsibility for it.

  • Assign the issue to the milestone v1.1 to indicate this task is due in v1.1, as given in the panel below.

  • Create a pull request for it, while taking care to follow the workflow prescribed in the panel below. Details of the photo to be added are given below the expandable panel.

  • Icon​​
    Adding a photo
    • Add a suitable photo of yourself, as described here.
    • The filename of the profile photo should be
      docs/images/github_username_in_lower_case.png
      Note the need for lowercase () 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.
    • At the same time, you can update the following links, which appear below the photo:
      • [homepage]: Link it to your home page, if you have one. Otherwise, you can remove it.
      • [github]: Link it to your GitHub profile page.
      • [portfolio]: This link is to be used for an optional deliverable called the Project Portfolio Page that will come later. You can remove it for now, and put it back if you decide to opt in for that deliverable at the end of the tP.
  • Get a team member to review the PR. For example, the reviewer can check if,
    the file is in the right location,
    the file name is as expected,
    the PR is sent from a fork, and is from a separate branch,
    commit messages comply with the Git Conventions.

  • Merge the PR.
    After that, sync your local repo and your fork with the team repo.

  • Good job on merging the first PR into the team repo!
  1. [each member] Update the AboutUs page as parallel PRs. In this step, we attempt to send parallel PRs that update the same page, which can result in merge conflicts (hence, you get to practice resolving merge conflicts in a team project):
  • Create an issue, and a PR, for the following task, similar to steps 3.2-3.5 above (do not merge the PR yet).

Updating the 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. Similarly, do not split the given .md files further into multiple files, as our grading script will check only those files.

  • Add your own details.
  • There is no need to mention the tutor/lecturer, but it is OK to do so.
  • 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.
  • Wait until all team members have sent the PR for the above step.
    Review each other's PRs while waiting.

FAQ What if a team member has not done this task? Can the rest proceed?

  • Merge one of the PRs sent in step 4.1 (e.g., the one that arrived first). If this causes conflicts in other PRs, resolve those conflicts.
    This week's tP briefing video (Part 2a -- v1.1, Workflow) has a section on how to resolve conflicts in PRs.
  • Merge the remaining PRs one at a time, while resolving merge conflicts as needed.
  • Check the AboutUs page in your team's repo to confirm that the page appears as expected. Here is an example.
    If something is not right, you might have to create another PR to rectify it.
  1. Congrats! You are done with this workflow practice session. It might have felt like a lot of 'jumping through hoops' for very little gain, but as you go through the tP, this 'workflow overhead' is expected to feel progressively less 'draggy'. Hopefully, it will be almost second nature to you by the time you finish the tP.

2 Update the README.md and site-wide settings

Now that you have learned the tP workflow, you can proceed to update a few more documents in the tP repo, as per tasks A and B below, following the same workflow (though doing parallel PRs is optional).

Recommended procedure for updating docs:

  1. Decide among yourselves who will update which parts of the document(s).
    All team members are expected to contribute to all aspects of documentation (e.g., user docs, developer docs, diagrams)
  2. Update the team repo by following the prescribed workflow:

Guidance on using documentation tools (e.g., how to preview changes locally before committing/pushing) 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:

Each member must PR their part of the documentation work. Reasons:

  1. We use Git data to detect contributions to documentation. If one person commits all documents on behalf of the entire team, our grading scripts will identify that person as the sole contributor to documentation.
  2. Git authorship data will help you identify the person responsible for specific bugs in documentation -- in the final submission, only the person(s) responsible for each bug is penalized for that bug.
  3. The project is intended as an exercise for you to practice using Git to manage changes to the same code in parallel.

FAQ When all members are updating the same document, can we create one issue and assign it to all?

A: Update the README.md 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 one screenshot/mockup, and ensure the new image has 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.
    The UI mockup can be a hand-drawn sketch or created using a tool such as PowerPoint, PlantUML, or Figma. Don't spend a lot of time on this, as this will eventually be replaced by a screenshot of the actual product.
    Can we use an AB3 screenshot for this? Only in the unlikely case that your final product UI is expected to look exactly the same as AB3.
  • 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).
  • Update all remaining contents of the page to match your own project (i.e., it should read like the README.md of an actual project, not that of a sample project given to students).

If you did the above updates correctly, your UI mockup and profile photos should appear on your project website and this Project List Page.

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/_config.yml and docs/_sass/minima/_base.scss if using Jekyll; in docs/_markbind/layouts/default.md if using MarkBind).

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

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

  • Add the following to the DG, based on your project notes from the previous weeks. No need to update other sections for now.
    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 that were considered but will not be included in the final product.
    • Use cases: Give representative use cases (textual form) 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: List whichever NFRs you think are reasonable for your product e.g., performance requirements, usability requirements, scalability requirements, etc.
      Some of the given project constraints can be framed as NFRs (e.g., Constraint-Portable) while others are purely for pedagogical/course-admin purposes (e.g., Constraint-Incremental).
    • 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. That is, do not limit them 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 look out for:

Add your DG content into the docs/DeveloperGuide.md (i.e., do not split that file further into multiple files), as only that file will be checked when our grading scripts look for your content contributions to the DG.

A similar restriction applies to the UG, i.e., add your content to the docs/UserGuide.md (do not split that file into multiple pages).

4 Start the next iteration

  • Stronger teams are welcome to stay one week ahead of the tP schedule. So, feel free to move on to next week's tP tasks, and get started on the next iteration (i.e., v1.2).