Week 4 [Mon, Jul 5th] - Project

Suppose you want to propose some changes to a GitHub repo (e.g., samplerepo-pr-practice) as a pull request (PR). Here is a scenario you can try in order to learn how to create PRs:

1. Fork the repo onto your GitHub account.

2. Clone it onto your computer.

3. Commit your changes e.g., add a new file with some contents and commit it.

• Option A - Commit changes to the master branch
• Option B - Commit to a new branch e.g., create a branch named add-intro (remember to switch to the master branch before creating a new branch) and add your commit to it.

4. Push the branch you updated (i.e., master branch or the new branch) to your fork, as explained here.

Pushing a branch to a remote repo

Here's how to push a branch to a remote repo:

Here's how to push a branch named add-intro to your own fork of a repo named samplerepo-pr-practice:

Normally: git push {remote repository} {branch}. Examples:

• git push origin master pushes the master branch to the repo named origin (i.e., the repo you cloned from)
• git push upstream-repo add-intro pushes the add-intro branch to the repo named upstream-repo

If pushing a branch you created locally to the remote for the first time, add the -u flag to get the local branch to track the new upstream branch:
e.g., git push -u origin add-intro

See git-scm.com/docs/git-push for details of the push command.

5. Initiate the PR creation:

1. Go to your fork.

2. Click on the Pull requests tab followed by the New pull request button. This will bring you to the 'Comparing changes' page.

3. Set the appropriate target repo and the branch that should receive your PR, using the base repository and base dropdowns. e.g.,
   base repository: se-edu/samplerepo-pr-practice base: master
   

   Normally, the default value shown in the dropdown is what you want but in case your fork has e.g., the repo you forked from is also a fork of a another repo, which means both of those are considered upstream repos of your forkmultiple upstream repos, the default may not be what you want.

4. Indicate which repo:branch contains your proposed code, using the head repository and compare dropdowns. e.g.,
   head repository: myrepo/samplerepo-pr-practice compare: master
   

6. Verify the proposed code: Verify that the diff view in the page shows the exact change you intend to propose. If it doesn't, commit the new code and push to the branchupdate the branch as necessary.

7. Submit the PR:

The next step of the PR life cycle is the PR review. The members of the repo that received your PR can now review your proposed changes.

• If they like the changes, they can merge the changes to their repo, which also closes the PR automatically.
• If they don't like it at all, they can simply close the PR too i.e., they reject your proposed change.
• In most cases, they will add comments to the PR to suggest further changes. When that happens, GitHub will notify you.

You can update the PR along the way too. Suppose PR reviewers suggested a certain improvement to your proposed code. To update your PR as per the suggestion, you can simply modify the code in your local repo, commit the updated code to the same master branch, and push to your fork as you did earlier. The PR will auto-update accordingly.

Sending PRs using the master branch is less common than sending PRs using separate branches. For example, suppose you wanted to propose two bug fixes that are not related to each other. In that case, it is more appropriate to send two separate PRs so that each fix can be reviewed, refined, and merged independently. But if you send PRs using the master branch only, both fixes (and any other change you do in the master branch) will appear in the PRs you create from it.

To create another PR while the current PR is still under review, create a new branch (remember to switch back to the master branch first), add your new proposed change in that branch, and create a new PR following the steps given above.

It is possible to create PRs within the same repo e.g., you can create a PR from branch feature-x to the master branch, within the same repo. Doing so will allow the code to be reviewed by other developers (using PR review mechanism) before it is merged.

The PR review stage is a dialog between the PR author and members of the repo that received the PR, in order to refine and eventually merge the PR.

Given below are some steps you can follow when reviewing a PR.

1. Locate the PR:

1. Go to the GitHub page of the repo.
2. Click on the Pull requests tab.
3. Click on the PR you want to review.

2. Read the PR description. It might contain information relevant to reviewing the PR.

3. Click on the Files changed tab to see the diff view.

4. Add review comments:

1. Hover over the line you want to comment on and click on the icon that appears on the left margin. That should create a text box for you to enter your comment.
   To mark multiple lines, click-and-drag the icon.
2. Enter your comment.
   This page @SE-EDU/guides has some best practices PR reviewers can follow.
3. After typing in the comment, click on the Start a review button (not the Add single comment button. This way, your comment is saved but not visible to others yet. It will be visible to others only when you have finished the entire review.
   

4. Repeat the above steps to add more comments.

5. Submit the review:

1. When there are no more comments to add, click on the Review changes button (on the top right of the diff page).
2. Type in an overall comment about the PR, if any. e.g.,

   Overall, I found your code easy to read for the most part except a few places
   where the nesting was too deep. I noted a few minor coding standard violations
   too. Some of the classes are getting quite long. Consider splitting into smaller
   classes if that makes sense.
   

   LGTM is often used in such overall comments, to indicate Looks good to merge.
   nit is another such term, used to indicate minor flaws e.g., LGTM, almost. Just a few nits to fix..
3. Choose Approve, Comment, or Request changes option as appropriate and click on the Submit review button.

The PR review stage is a dialog between the PR author and members of the repo that received the PR, in order to refine and eventually merge the PR.

Given below are some steps you can follow when reviewing a PR.

1. Locate the PR:

1. Go to the GitHub page of the repo.
2. Click on the Pull requests tab.
3. Click on the PR you want to review.

2. Read the PR description. It might contain information relevant to reviewing the PR.

3. Click on the Files changed tab to see the diff view.

4. Add review comments:

1. Hover over the line you want to comment on and click on the icon that appears on the left margin. That should create a text box for you to enter your comment.
   To mark multiple lines, click-and-drag the icon.
2. Enter your comment.
   This page @SE-EDU/guides has some best practices PR reviewers can follow.
3. After typing in the comment, click on the Start a review button (not the Add single comment button. This way, your comment is saved but not visible to others yet. It will be visible to others only when you have finished the entire review.
   

4. Repeat the above steps to add more comments.

5. Submit the review:

1. When there are no more comments to add, click on the Review changes button (on the top right of the diff page).
2. Type in an overall comment about the PR, if any. e.g.,

   Overall, I found your code easy to read for the most part except a few places
   where the nesting was too deep. I noted a few minor coding standard violations
   too. Some of the classes are getting quite long. Consider splitting into smaller
   classes if that makes sense.
   

   LGTM is often used in such overall comments, to indicate Looks good to merge.
   nit is another such term, used to indicate minor flaws e.g., LGTM, almost. Just a few nits to fix..
3. Choose Approve, Comment, or Request changes option as appropriate and click on the Submit review button.

project expectations

Outcomes

The high-level learning outcome of the team project (tP):

Can contribute production quality SE work to a small/medium software project

The focus of the tP is to learn the following aspects:

1. coding (taken for granted, not focused on specifically)
2. working in a team
3. process/workflow
4. documentation
5. scheduling and tracking project progress, meeting delivery deadline
6. quality assurance

Target User & Value Proposition

You are expected to:

• Define a very specific target user profile.
  We require you to narrow down the target user profile as opposed to trying to make it as general as possible. Here is an example direction of narrowing down target user: anybody → teachers → university teachers → tech savvy university teachers → CS2113/T instructors.
  
  Be careful not to contradict given project constraints when defining the user profile e.g. the target user should still prefer typing over mouse actions.

• Define a clear value proposition that matches the target user profile i.e., what problem does the product solve? how does it make the user's life easier?
  You should also define the scope clearly i.e., boundary beyond which the app will not help e.g., the app will help to manage tasks within a single project only (no support for multiple projects).
• Optimize the product to the chosen target users i.e., add features that are especially/only applicable for target users (to make the app especially attractive to them).

  • Example 1: If the product targets CS2113/T instructors, there can be features that are applicable to them only, such as the ability to see a link to a student's project on GitHub

  • Example 2: If your app manages contacts, you can optimize its features based on,

    • the profession of the target user e.g. doctors, salesmen, teachers, etc.
    • the nature/scale of contacts e.g. huge number of contacts (for HR admins, user group admins), mostly incomplete contacts, highly volatile contact details, contacts become inactive after a specific period (e.g. contract employees)
    • what users do with the contacts e.g. organize group events, share info, do business, do analytics

    Your project will be graded based on how well the features match the target user profile and how well the features fit-together.

Your project should comply with the following constraints. Reason: to increase comparability among projects and to maximize applicability of module learning outcomes in the project.

In addition, you are strongly encouraged to follow these recommendations as they can help increase your project score.

1. Project Grading: Product Design [ 5 marks]

Evaluates:

• how well your features fit together to form a cohesive product
  (not how many features or how big/novel/interesting/difficult the features are)
• how well it matches the target user