Skip to content

Assignment 1: Using Git & GitHub to Get Ready for Collaborative JavaScript Development

Possible Points Due Date
50 pts Friday, September 4th - 11:59pm

Overview

After this assignment, you should be able to use Git and GitHub for your teamwork in this course and other projects. You should know about the GitFlow workflow and how to collaborate with other developers on their projects. You will practice that workflow on Mixtape, a small React album browser that ships with two real defects: you will read a failing CI pipeline, open an issue for each defect, fix each one on its own branch, and get your changes reviewed and merged.

Mixtape is deliberately written in the same style as the codebase you will work on for the Software Development Project — React function components, custom hooks, a src/utils.js of small pure helpers, and a test suite split between unit tests and UI tests. It is a different application, so nothing transfers by copy and paste, but every pattern should look familiar when you get to the project.

Using AI Coding Assistants

You are welcome to use AI assistants such as ChatGPT or GitHub Copilot on this assignment. If you do, you must record it: add an entry to your Collaboration Log noting which tool you used and what you used it for. Review the full Policy on the Use of AI Coding Tools in the syllabus before you start. Remember that you are responsible for any errors an AI tool introduces, so read and verify anything it produces.

Prerequisites

Authenticating GitHub on your local Machine

GitHub requires two-factor authentication and token-based access to clone repositories using https. Check out this article on cloning with HTTPS URLs for more information.

Managing more than one version of Node

If you already have an older Node on your machine, nvm is the usual way to keep several versions side by side. Once it is installed, nvm install --lts && nvm use --lts will give you Node 24.

Part 1a: Joining the Course and Getting Your Repository

This course distributes assignments through UCF Code Classroom, our own classroom app. You join the course once, using the link below, and every assignment for the rest of the semester then appears there — you will not need a new link each time.

Joining takes three steps:

  • Sign in with GitHub. Use the account you intend to submit coursework from for the rest of the semester. Only your username, name, and email are read.
  • Pick your name from the class roster. This is how your GitHub account gets matched to you in the gradebook, so choose carefully.
  • Open Assignment 1. Code Classroom creates a private repository of your own from the Mixtape template. There is nothing to fork.

Once your repository exists, clone it and get the app running:

npm install
npm run dev
  • Open the URL that npm run dev prints and click around. Two things in this app are visibly wrong. Make a note of what you notice before you read any code.

Check that Issues are enabled

Under the Settings tab of your repository, confirm that the "Issues" checkbox is ticked in the "Features" section. You will need the Issues tab in Part 2.

Part 1b: Run a GitHub Action Workflow

  • On GitHub, click the Actions tab, enable the workflows if prompted, and select the "Lint & Test" workflow
  • Click on the "Run workflow" dropdown, then the "Run workflow" button (leave Branch set to main). This runs the linter and the full test suite on the project

Our GitHub Actions pipeline reports that the main branch is broken! Let's walk through the process of fixing it.

Merging to main

In practice, you should not merge a branch into the main branch that could cause main to fail. This way, we can ensure that all the code on main is our most recent working product.

Part 2: Setting up a Kanban Board and Creating Issues

  • Click through the build output and take a look at which tests are failing. There are two distinct defects. Take note of the test names and the files they live in — you should use these when naming your issues!
  • When your Code Classroom created your repository, it also created and linked a "project board". This allows you to create and manage issues and other milestones. Navigate to the project board by click the "Project" tab from your repo home page, and then click on the Project. Once in the project board, click on the "View" button in the top right (with the gear icon), and change the view to the "Board" view, and click "Save View".
  • Under the Issues tab, create one issue per defect (so, two issues). In each issue, describe the symptom you can see in the running app and the test that catches it.
  • Assign yourself to both issues, and add the issues to the project Kanban board you just created using the "Projects" option (two fields below "Assignees")
  • Note that in the future you can share a Kanban/Project board with your teammates or make it public so they have access to it.

Two kinds of test

npm test runs both suites at once, but you can run them separately while you work:

  • npm run test:unit-only — the unit tests in src/utils.test.js, which call the helper functions directly with no rendering
  • npm run test:ui-only — the UI tests, which render real components and interact with them the way a person would

One of the defects is caught by both kinds of test. The other is only caught by the UI tests, which is worth thinking about.

Part 3: Branching, Committing, and Pushing

  • On your local machine, create a new branch with a name relevant to the issue you are addressing (e.g. "fix-title-truncation", "fix-case-sensitive-search"). For this assignment, be sure to create two branches, one for each of the issues that you need to fix.
  • Fix the defect, then add and commit the changes
  • Commits should start with a verb describing what the commit does to the codebase (e.g. "Remove faulty condition from getCustomerDetails", "Fix failing CompositeTestCase", "Fix issue #21")
  • Re-run npm test before you push, and confirm the tests for your defect now pass
  • Push the branch to remote
git push --set-upstream origin <your-branch-name>

Fix the code, not the test

Both failing tests describe the behaviour the app is supposed to have. Your job is to change the application code so the existing tests pass. Editing or deleting a test to make CI green will receive no credit.

Part 4: Writing Pull Requests

  • On GitHub, create a pull request to merge the changes from the branch you have just pushed into main
  • Name your pull request appropriately
  • In the description, describe what changes have been made to address the issue, and how those changes have been tested
  • Notice that the GitHub Actions workflow runs automatically when you create the pull request! Note that CI will not go fully green until both defects are fixed, i.e. both pull requests are merged. This is expected. As long as the tests covering your defect now pass, go ahead and merge.
  • Link the issue you created to the pull request
  • Review your own code (your teammates will do this for you in the future)
JavaScript and testing resources

These pointers will help with the changes you need to make - String.prototype.slice, String.prototype.toLowerCase, Vitest expect, Testing Library queries

Part 5a: Doing Code Reviews and Resolving Merge Conflicts

  • Review your code (use the review changes button). In this scenario, you won't be able to approve your own changes since you created them. However, if they look good, you can move to the next step! If not, go and revise your code in your editor.
  • Once your PR has been reviewed, merge your changes! Resolve any merge conflicts that arise accordingly
  • Return to the Kanban board. If everything was set up correctly, the issue should automatically move into the Done column

Part 5b: Check GitHub Actions

  • Click on the Actions tab and open the most recent run on your main branch. Once both defects are fixed, the linter and all 23 tests should pass, and a green check should show

Turning in the Assignment & Grading Rubric

All you upload is your repository URL. Make sure your work is pushed to main, that you add your url, and you upload the AI collaboration log if you used AI to help you with the assignment. Due date is Friday September 4th at 11:59pm.

The grading for this project will be broken down as follows:

  • Part One: Joining the Course & GitHub Actions - (10 points total)
  • Part Two: Kanban Board & Issues - (10 points total)
  • Part Three: Branching Committing & Pushing - (10 points total)
  • Part Four: Writing Pull Requests - (10 points total)
  • Part Five: Code Reviews, Resolving Merge Conflicts & Passing GitHub Actions - (10 points total)

Optional, if you would like to go further

Once CI is green, make one small change of your own on a third branch: a different accent color, sorting the grid newest-first, showing the genre on each card, whatever you like. Take it through the same issue, branch, pull request, review, merge cycle. This is not graded, but it is good practice for the project.