Project 1B: Starter Task¶

Deliverables¶

Starter Task - 45 points - due Friday, September 18th, 11:59pm

GitHub Issue (10 pts)
Code Documentation (10 pts)
GitHub Pull Request (15 pts)
Written Assignment (15 pts)

Onboarding¶

Now that you have the project running, the development team would like to give you an onboarding assignment.

Documentation Documentation Documentation! Every one of these projects has corners of the codebase that are under-explained — that is true of essentially all real software. Reading unfamiliar code closely enough to explain it back is the single fastest way to learn a system, and it produces something useful for the next person who has to touch it.

To prepare you for working with the project, we would like you to document a part of the codebase.

Prerequisites¶

Onboarding Materials¶

Before jumping into the codebase, please review the course syllabus and be sure you have access to each of the following:

Ed Discussions - check your email for an invite link
Webcourses
Your team's repository, from UCF Code Classroom

If you run into any trouble accessing the above or have any questions, reach out to the instructors.

Git & GitHub¶

In this project and throughout the rest of this course, you will be expected to work extensively with Git and GitHub. Specifically for this project, you should be familiar with:

Cloning repositories and working on branches
Understanding general Git flow - pulling, branching, adding, committing, pushing, merging
Creating GitHub Issues and using related features (labels, assignees, milestones)
Creating GitHub Pull Requests and using related features (linking to issues)
Creating GitHub Project Boards

You should have gotten more familiar with these topics in Assignment 1, but if needed, please refer to the Resources & Documentation section.

GitHub Issue (10 pts)¶

First, choose a single source file in your team's project to document, and open a GitHub Issue in your team's repository to declare which file you are taking.

There are some restrictions on the file you can pick. Specifically, the file must:

Be a source file in the project's main source tree — not configuration, not generated code, not vendored third-party code, and not a test file. Where that tree lives differs by project (src/, app/, apps/*/, packages/*/src/, or the Go package directories in Gitea), and working out which directories hold the real components is itself part of the exercise — explore the repository, and use an AI assistant to help you get oriented if that is useful. If you are still unsure, ask on Ed Discussions and name the directory you are considering.
Contain at least 20 lines of real code, not counting imports, comments, and blank lines.
Not already be claimed by a teammate. Look through the open issues in your repository before you pick, so two of you do not document the same file. There is an incentive to start early here.

The file does not have to be completely undocumented

Plenty of files in these projects have a few scattered comments without being properly documented. That is fine — a file with room to add meaningful documentation is a good choice, and you do not need to hunt for one that has no comments at all.

You can change your mind about which file to take

If you get into a file and find it is a poor fit — too thin, mostly generated, already thoroughly documented — just close your original issue with a short note saying why, and open a new one for the file you are switching to. No penalty. Do it before you have gone far, so your teammates know which file is actually free.

Title the task appropriately, such as Document <file path> to explain functionality, and mention the file in the description. To prevent ambiguities between similarly-named files, be sure to use the full file path in both the title and the description.

Issue Guidelines

Issues titles should provide a high-level overview of what the problem is (e.g. "Navbar button UI bugs", "Unexpected registration validation errors"). Sometimes, issues are used to propose new features (e.g. "Add CSV export feature").

Issue descriptions should then elaborate on the title. For feature-level bugs, this may include providing information about how to reproduce the bug; for codebase-level changes, you can name specific files.

Because Code Classroom gives your whole team write access to the repository, you can assign the issue to yourself directly using the Assignees field in the sidebar. Do that as soon as you open it — that is what tells your teammates the file is taken.

Code Documentation (10 pts)¶

Create a feature branch in your team's repository and write the documentation for your selected file.

git checkout main && git pull origin main
git checkout -b docs/document-<short-file-name>

You should start with the following steps:

Use your project's own documentation conventions. Look at how neighbouring files are commented before you write anything: JSDoc/TSDoc in the TypeScript projects, YARD or plain # comments in the Ruby projects, godoc-style comments in Gitea. Matching local convention is part of the exercise — a real contribution that ignores house style gets sent back in review.
First, go through and identify each function, method, or exported symbol in your file.
Next, use the code archaeology techniques we discussed in the Week 1 lectures to work out what each one does, and write a comment summarizing its functionality.
After you have summarized each function, summarize the purpose of the entire file at the top of the file.

What if the project has no consistent documentation convention?

This is a very common situation in open-source ecosystems, and several projects in this course are in it: a handful of files use a structured format such as TSDoc, and the rest have ordinary // comments scattered around with no discernible house style.

When there is no convention to follow, decide on one and write it down. Borrow or adapt guidelines from another open-source project in the same language that does have good documentation practices, and credit where you took them from — in your pull request description for this assignment, and in docs/cen5016/standards.md once you get to SDE Project Checkpoint 1.

Do not take the absence of a convention as licence to be unstructured. Being able to say "here is the standard we adopted and here is where it came from" is the professional answer, and it is what your team will be graded on later.

Your changes should pass the project's linter and test suite, so be sure to run both locally before you push.

Pre-existing failures and lint errors are not your responsibility

Several of these projects have test suites that do not fully pass on a fresh clone, and linters that report hundreds of warnings on code nobody has touched in years — one project reports over 270 problems out of the box. You are not expected to fix any of that, and it will not cost you points.

What matters is that your own change is clean: run the linter, look for your file in the output, and fix anything that your edits introduced. If your file does not appear in the linter output at all, you are done.

Correctness of Comments & AI Tools

Note that we will be (loosely) assessing the correctness of your comments. You are free to use AI-based tools to help with your comprehension of the code, however be sure to double check the model's understanding!! They can often be (very) wrong about the purpose and functionality of code, and if you use a model's incorrect explanation of something in your comments, you will be held responsible.

This matters more here than it did on a small codebase. An agent that has only seen a few hundred lines of a large system will confidently invent an explanation for code whose real behaviour depends on something three files away. Verify against the code.

GitHub Pull Request (15 pts)¶

As you work, be sure to periodically commit your changes. Your commit message(s) must clearly describe what is changing.

Branch and Commit Guidelines

Branch names should be short and provide a description of what you will be doing on that branch (e.g. "fix-header-sizing-issue", "fix-multiple-dialog-bug", "add-sorting-feature"). When working with others, you can also append your username to signal which branches are yours (e.g. "5016ta/add-sorting-feature").

Commits should start with a verb and provide a description of what they are doing to the codebase (e.g. "Remove faulty condition from getCustomerDetails", "Fix failing CompositeTestCase", "Fix issue #21" ).

Once you are satisfied, open a pull request from your branch back to main in your team's repository. Similar to the Issue, your PR title should mention the full path of the file you have changed. The PR body should summarize the changes you made and use one of the linking keywords to link the issue that you previously opened (e.g. adding resolves #313 will signal to GitHub that this PR resolves issue number 313).

Pull Request Guidelines

Pull request titles should describe what high-level changes were made to the codebase. Generally, they give a concise summary of all the commit messages.

Pull request descriptions should describe what changes have been made in more detail and how the changes have been tested.

Each of these projects runs its own CI on pull requests, and some of those pipelines are substantial — they may take a while, and they may run checks you have not seen before. Check on your pull request periodically to make sure everything passes.

CI Failures

If a check fails on GitHub but the same command passes locally, read the failure output before re-running. Some failures are genuine environment differences worth understanding; others are flaky and clear on a re-run. Knowing which is which is a skill you will use constantly.

A third category exists in these repositories, and it is the most common one: jobs that fail on any pull request regardless of its contents. A job may need infrastructure the upstream maintainers provide, or hit Resource not accessible by integration because it wants permissions the repository does not grant — and when such a job gates the others, everything downstream shows as "skipped" rather than running.

None of this costs you points. Any of the following is acceptable:

Leave it. Note in your PR description which check failed and why you believe it is unrelated to your change.
Fix it, if you can work out the configuration change it needs.
Delete the job from .github/workflows/ for the purposes of the course project.

Replicating the full CI setup of a mature open-source ecosystem is often not realistic. Post on Ed Discussions if you are not sure which category a failure falls into.

If all of the checks that can pass have passed, you will see a green checkmark next to your pull request. This signals that you have completed the implementation aspect of this assignment! ✅

Yes, go ahead and merge your pull request

You do not need to wait for it to be graded or reviewed by an instructor. Merge it into your team repository's main branch once you are satisfied with it — that is the end of the workflow, and it is what you will be doing on the project for the rest of the semester.

Written Assignment (15 pts)¶

After you have completed all of the above tasks, we will ask you some questions relevant to your team's project. Fill out and submit the Assignment 2 Written Assignment available on Webcourses.

Please include links to your PR and Issue in your written assignment!!

Grading¶

To receive full credit for this project, we expect: