Homework 5: More Version Control (git)

This assignment continues HW4’s focus on learning how to use git as a version control system. In contrast to HW4, HW5 is completely focused on working with others; you’ll work on a website together with the entire class! In the process, you’ll practice working with a remote repository, using merge requests, and potentially resolving merge conflicts.

Task 1: Collaborate on a shared GitLab repo¶

Everybody in CSE 391 has recently been hired by FAANG (hooray)! The frontend team wants to build a page that features all the incredible staff at the company. They’ve decided to distribute this task — i.e., each employee will add themselves to the staff page. This includes you!

Problem 1: View and clone the repository¶

You should have been given access to the following repository: cse391/24su/faang. If you cannot view this repository due to a permissions problem, please double-check your email for an invitation to the repository or contact course staff.

Your first step will be to clone the repository to your working computer (e.g. attu, vergil, or the CSE VM):

$ git clone git@gitlab.cs.washington.edu:cse391/24su/faang.git

You should now be able to cd into the faang folder and see a handful of files; most important to you are Product.java and Staff.java. You should also be able to compile all of the java files and “build” the site via:

$ javac *.java && java GenerateSite

Problem 2: Create a new branch for your additions to the staff page¶

Since so many people are working on this project, we won’t directly push to main; instead, we’ll create our own feature branch to make our own changes.

Create a new branch from the main branch. We suggest the name <GITLAB_USERNAME>_staff_page, where <GITLAB_USERNAME> is your GitLab username (e.g. mxw).

Problem 3: Add your bio to the staff page¶

In the repository, the Staff.java file stores all of the employees at FAANG as methods that return an Employee object (representing you).

Open the Staff.java file in your favourite text editor, while on your feature branch. Create a method — which must be named after your GitLab username — that returns one such Employee object.

What goes into an Employee? Each employee has a:

• String name
• String job title (position)
• String bio (description)
• String picture file path (picture) and accompanying String alt text (altText)

For the name, position, and description, feel free to pick arbitrary (PG-13) Strings.

For the picture, pick something that you feel best represents you (does not have to be a photo of you). After you find a good photo, you should:

• place a copy of the image in the images/staff directory
• make the picture parameter of Employee the name of the file (not including the images/staff prefix, but including the extension)
• add alt text that accurately describes the content of the image; if you’re curious about what makes “good alt text”, Deque’s How to Design Great Alt Text is a great intro, while the MDN docs on the alt property give a more technical overview.

Then, make sure that the entire program still compiles after your edits. If it doesn’t compile, you won’t be able to merge your changes!

This would be a good time to add and commit your changes.

Problem 4: Add your product to the products page¶

A similar page Products.java lists all the products FAANG sells. Open it in your favourite text editor (and still on your feature branch) and add a Product. This product must be named after your GitLab username. Similar to an Employee, a Product has:

• String name
• String description
• String picture file path (picture) and accompanying String alt text (altText)
• double price of the product

Similar to the previous task, feel free to pick arbitrary Strings for the name and description, pick a valid image (this time, inside of images/products), and add some descriptive alt text. Note that the last parameter, the price, is a double, not a String.

Then, make sure that the entire program still compiles after your edits. If it doesn’t compile, you won’t be able to merge your changes!

This would be a good time to add and commit your changes.

Problem 5: Push your change to remote¶

Now, use the appropriate commands to push your branch to the remote repository.

You should be able to see your commits in GitLab using the following link (replacing GITLAB_USERNAME with your GitLab username):

https://gitlab.cs.washington.edu/cse391/24su/faang/tree/GITLAB_USERNAME_staff_page

Alternatively, you can double-check by:

1. navigating to the repository main page
2. click on the “Branches” page under “Code”, on the sidebar
3. scroll through all of the branches of the repository to find yours

Problem 6: Create a merge request¶

When working on teams, you’ll typically have another teammate review your code before merging your changes into main. GitLab’s mechanism to do this is called a “merge request”, which lets teammates to review, comment on, and approve your work.

Create a merge request for your feature branch on GitLab. To do so,

1. go to the repository main page
2. select “Merge Requests” on the left side-nav, and click “New Merge Request”
3. select your own branch in the “Select source branch” dropdown, and set your target branch to main
4. click “Compare branches and continue”
5. give your merge request a reasonable title, and write a description of your changes
6. while often we want to delete the branch, be sure that you UNCHECK the box to delete the branch — we need the branch to still exist to give you credit in Gradescope
7. leave the other dropdowns and options as-is, and submit your merge request!

Once this happens, GitLab will automatically run some code to make sure that:

• your branch can be merged properly (with no merge conflicts)
• your branch is “up-to-date” with the main branch. if things have been merged into main since you made your branch, this will likely be false!
  • to fix this, merge the main branch back into your own feature branch. You can do this locally or via the GitLab UI.
• your merge request doesn’t “break” the site. For this project, that means:
  1. all the .java files compile and run with no errors
  2. you haven’t removed any lines of the codebase in your merge request (this is to prevent you from accidentally deleting other people’s entries)
  3. you haven’t edited any files outside of Staff.java and Product.java (this is to prevent you from accidentally breaking the HTML generation)

Problem 7: Comment on your merge request¶

Typically, you’ll request a review from your teammate(s). Right now, they’re a bit too busy with their own changes, so your own “review” will suffice. Leave at least one comment on a change in your merge request. It can say whatever you’d like!

Problem 8: Approve and merge your merge request¶

Let’s incorporate your changes into main so it can make it on the main website!

There is a “Merge” button close to the top of your page. If you’re able to click it, go for it - you’re done this step!

However, the merge button may be disabled. This is for one of four reasons:

1. there is a merge conflict with main
2. your branch is not up-to-date with the main branch on GitLab
3. your code does not compile and run with no errors
4. your merge request removes one or more lines from the existing codebase, or edits files that are not Staff.java or Product.java

It is your responsibility to resolve these problems!

1. You can resolve merge conflicts using the GitLab merge conflict UI (“Resolve conflicts”) or with the command-line. - make sure to not accidentally delete other people’s changes!!
2. You can merge the main branch on GitLab back into your feature branch
3. You can debug your program if it does not compile / runs incorrectly (this is usually a typo)
4. You can add extra commits that restore the lines you’ve accidentally removed, or undo changes to other files

Problem 9: Turn In¶

To submit your work, you will submit the homework5.sh file to Gradescope.

You can get the homework5.sh file by running this command in your terminal:

wget https://courses.cs.washington.edu/courses/cse391/24su/homework/hw5/homework5.sh

This file containts just one function called print_username. Unlike the other homeworks, you will leave the echo command but replace the text string with your GitLab username.

function print_username {
  echo "your gitlab username here"
}

To calculate your final score on this assignment, sum the individual scores from Gradescope.

• if your score is between [0, 1), you will get 0 points
• if your score is between [1.0, 1.5), you will get 1 point
• if your score is between [1.5, 2], you will get 2 points

However, this score is provisional: if we notice that you’ve submitted someone else’s username, we reserve the right to change your score.

This autograder is still new (and we’ve recently added even more infrastructure). Running into problems? Post on Ed!

Tips¶

• Make a mistake? DO NOT try to go back and modify previous commits - this gets you in a huge mess when working on a shared project (like this)!
  • the autograder is designed in a way where you can keep adding commits/merge requests without penalty
  • if your methods (for Product.java and Staff.java) have the wrong name, you should add new methods rather than deleting them (to workaround the check that prevents you from deleting others’ code)
  • please post on Ed or come to office hours if you need extra help!
• If you run git status and see "Your branch is ahead of 'origin/main' by N commits", your local branch has commits that have not been pushed to remote yet.
• git will not allow you to pull updates into your repo while you have unstaged changes. Therefore, you need to first git add and commit your changes before pulling.

(Optional) Task 2: Use the website¶

The repository contains a rudimentary static site generator, which is a type of software that converts text input into a website (made of HTML, CSS, and JS). This one is far from complete (there are many, many great ones — MkDocs makes the 391 website!), but is intentionally written with a subset of Java that almost only uses features taught in intro.

If you’d like, you can actually browse the output of the site and fiddle around! This isn’t strictly necessary for your grade, though it may help you debug why the site doesn’t work the way you expect.

The “Easy” Way¶

We’ve set up something called “continuous deployment” that rebuilds and deploys the site on each commit to the main branch. You can visit the site at https://cse391.pages.cs.washington.edu/24su/faang/.

But, it’s more fun to do it yourself, with…

The “Hard” Way: Build it Yourself!¶

You can compile all the Java files in the repository’s root directory and then run the GenerateSite program (the entrypoint for this site generator).

javac *.java && java GenerateSite

This will produce an index.html file that contains a list of all the products and staff, as well as individual .html files for each product and employee.

To view the website, you have a few options:

1. If you’re working locally you can navigate to the faang directory using Finder (macOS) or File Explorer (Windows) and double click on the index.html file. This should open the website in your default web browser.
2. If you’re working on attu (or vergil, etc.) you will need to copy your files over to your local machine to view them. scp’s -r flag helps you copy folders (rather than individual files); here’s one example:

   scp -r CSENetID@attu.cs.washington.edu:/path/to/faang .
   

3. If you’re working on the VM, you can use the File Manager application to navigate to the faang directory and double click on the index.html file, which should open the site in Firefox.

Note: we’ve intentionally added some items to our .gitignore that can be built from source. In particular, compiling the .java files produces .class files, and running GenerateSite creates the .html files. As a result, we’ve chosen not to commit these files, since they “duplicate” information.