Skip to content

Project 1A: Build Checkpoint

Deliverables

Build Checkpoint – 5 points – due Friday, September 18th, 11:59pm

Getting Started

Repository Setup

Your team's repository is distributed through UCF Code Classroom. You joined the course there for Assignment 1 and that membership carries over, so there is no new link to accept — sign in, open Assignment 2, and your team's repository will be there.

Code Classroom creates the repository for your team, so there is nothing to fork. Clone it and work on branches:

git clone https://github.com/<your-team-repository>.git
cd <your-team-repository>

Clone your team repository, not the upstream project

Clone the repository Code Classroom gave your team. If you clone the upstream project instead, you will not be able to push branches, and any pull request you open will go to the real maintainers rather than to us.

Direct any questions to the course staff. Do not contact the maintainers of these projects for assistance with your homework.

If your repository is not in Code Classroom yet

Repositories appear once teams are assigned. If yours is missing after the announcement goes out, post on Ed Discussions rather than creating your own — a repository you make yourself will not be collected at the deadline.

GitHub Actions on your team repository

Actions have been enabled centrally on every team repository, so there is nothing you need to switch on. If the Actions tab is missing from your repository, or the workflows are queued and never start, that is an organization-level setting on our end — post on Ed Discussions and we will fix it.

It does not block this assignment. Part 1 asks you to run the test suite locally, and Part 2 is a documentation change, so you can complete both while Actions is being sorted out.

A short explanation of why these pipelines are unusual: each repository runs the real project's own development pipeline, and some of those runs would take days or need hardware the open-source project provides. We pruned the most expensive and the obviously-unrunnable jobs so that what is left is actually useful to you. Some nightly jobs still run, and the number of CI jobs varies a lot between projects — one or two on some, more than twenty on others. That is simply the nature of eight different real systems.

Installing and Running the Project

Start with STUDENTS.md in the root of your repository. Every project in this course has one. It is written for you specifically — it tells you how to install dependencies and get that particular project running, and it is the first thing you should read.

After that, and when STUDENTS.md does not cover something:

  • The repository's README.md
  • Any CONTRIBUTING.md, DEVELOPMENT.md, or docs/ directory
  • The project's official documentation site, linked from the project table

Every one of the eight projects installs differently, so there is no single set of steps we can give you here. We have collected the general prerequisites for each stack — Node, Ruby, Go, Docker and so on — on the Environment Setup page. Install those first, then follow STUDENTS.md.

Debug before you ask, but do not grind for hours

In this class we expect students to first try debugging errors on their own; this includes following stack traces, searching up error strings and unfamiliar outputs, and reading the project's own issue tracker, where someone has very often hit your exact problem already.

That said, these are large systems. If getting the project running is taking you more than a few hours, stop and ask for help on Ed Discussions. Post the exact command you ran and the exact error you got.

Once the project is running, take some time to click through it and explore the features it offers. You are going to be working on this system for the rest of the semester, so it is worth understanding what it actually does before you change any of it.

Analysis Tools

When working on an existing codebase, especially in a collaborative setting, we want to ensure that none of our changes introduce unexpected bugs or issues for other developers. To fulfill these goals, we often use different tools to help us evaluate our code.

Every one of these projects ships with a test suite, and nearly all of them ship with a linter or formatter as well. Find them — the commands are usually in the scripts section of package.json, in a Makefile, in CONTRIBUTING.md, or in the CI workflow files under .github/workflows/. Reading the CI configuration is often the fastest way to learn exactly what a project expects a contributor to run before pushing.

Run the test suite before you change anything, so that you know what your project looks like before you touch it.

If the baseline tests do not pass — that is fine, and you do not have to fix them

A failing test on a fresh clone will not cost you points on this assignment. Several of these projects have suites that do not go fully green outside the maintainers' own CI environment, and chasing that down is not what this checkpoint is for.

It is still worth understanding why, because that is genuinely useful information about your project. Common causes we have already seen this semester:

  • The suite needs a database, a container, or environment variables that are not set.
  • Time zone assumptions. Several suites only pass under UTC — try TZ=UTC <your test command> (e.g. TZ=UTC make test-backend on Gitea).
  • Tests that render views or depend on a dev server that is not running in the test environment.
  • Windows path and line-ending differences. Use WSL2 and clone inside the Linux filesystem, not under /mnt/c/.

Note down which tests fail and why, try the project's own troubleshooting docs, and ask on Ed Discussions if you are curious or stuck. Then take your screenshot and move on — failures and all.

More on Analysis Tools

A linter is a tool that directly analyzes your source code for common errors. A test suite is a set of test cases that you write for a software program to show that it has some specified set of behaviors; our testing tool provides a framework to structure our test cases, runs the test suite, and generates a report of which tests pass/fail.

We will do a more in-depth exploration of analysis tools later in the course. For now, just know that these tools exist for you to use in evaluating your code.

Build Checkpoint (5 pts)

Upon completing the above steps, take screenshots of

  • the project running locally in your browser or terminal, and
  • the output of the test suite

Both must be from the project running on your own machine — a local npm run dev (or your project's equivalent) and a local test run. Screenshots of a GitHub Actions run do not show us what we are looking for here, which is that you have the system building on your own hardware.

It helps if the URL or the command is visible (for a web application, the localhost address in the browser bar; for the test run, the terminal showing the command you ran), but it is not a requirement — what we are grading is the output.

What exactly to capture for the test run

The final summary is enough. The passed/failed/skipped counts at the end of the run tell us what we need to know. You do not need to capture the intermediary output, the per-test log lines, or the whole scrollback.

A few situations that have come up, all of which are fine:

  • Your project has several test suites (unit, integration, E2E, UI). Submit one screenshot per suite — Webcourses accepts multiple attachments. Any one suite is enough for credit, so do not hold up your submission trying to get all of them running.
  • The output is thousands of lines and will not fit in a screenshot. Either capture just the summary at the end, or paste the full output into a PDF and submit that instead.
  • Some tests fail. Submit it as it is. See the note above — you are not expected to fix them.

Submit the screenshots to Webcourses.

Grading

To receive full credit for this checkpoint, we expect:

  • A Webcourses submission of two screenshots showing a local running build of your team's project and the output of its test suite