Project 1B: Fakeflix Documentation¶

Deliverables¶

Starter Task - 45 points - due Friday, September 20th, 11:59PM

GitHub Issue (10 pts)
FakeflixDocumentation (10 pts)
GitHub Pull Request (15 pts)
Gradescope Written Assignment (15 pts)

Onboarding¶

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

Documentation Documentation Documentation! Driven by their level-headed engineering manager, the team is currently undertaking a major code documentation overhaul and summarizing the behavior of functions and files across the project. They were running into technical debt that was making it difficult to continue the development of the project.

To prepare you for working with the project, the team would like you to assist with documenting different parts 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

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:

Forking/cloning GitHub repositories
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 if needed.

GitHub Issue (10 pts)¶

First, choose a single JavaScript or jsx file (no html or css files allowed!) to document and open a GitHub Issue in the class repository to declare which file you will be translating.

There are some restrictions on the .js or .jsx file that you can pick. Specifically, the file must:

Be in the src/ folder
Contain at least 20 lines of non-import statement code before you start translating it. Files like src/hooks/useGenreConversion.js are not allowed due to the length requirements.
Be a file that no one else in the class has picked and created an issue for. We expect you to look through existing issues, if any, to avoid such duplication (thus, there is an incentive for you to start early!)

Title the task appropriately, such as Documenting <file name> to explain functionality, and mention the file name in the description. To prevent ambiguities between similarly-named files, be sure to use the full file path (src/../xx.js) in the title and 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.

Then, assign yourself to the Issue by leaving a comment that says exactly "I would like to work on this please!" (note that you have to use this exact phrase to trigger the automated assignment feature, as the bot looks for this phrase).

You should soon see another comment by myself (kpmoran) which is triggered by a GitHub bot informing you that you have been successfully assigned to this issue.

Bot Issue Assignment

Why Bot Assignment?

You might be curious as to why we are using a GitHub bot instead of directly assigning yourself to the issue. As you aren’t officially recognized as a collaborator of CEN-5016/Fakeflix-UCF, GitHub adds some restrictions to your permissions for security purposes, including not being able to assign yourself to an issue. Hence, we are using a bot to work around these restrictions. This is similar to how you would request issues on an Open Source project!

For future projects, you will have full control over these GitHub features such as managing assignees, adding labels, creating milestones, and more.

Fakeflix Documentation (10 pts)¶

Back in your own fork, create a feature branch and write the documentation for your selected file. You should start with the following steps:

You will be using Javascript comments to add your documentation. If you are unfamiliar with how comments work in Javascript, please see this resource.
First, go through and identify each function in your file. *Note that functions in Javascript can be declared in a few different ways! Read up on functions in the MDN docs if you are unfamiliar.
Next, use the techniques we discussed from our Week 1 Lecture to try and understand what each function does, and write a comment summarizing it's functionality.
After you have summarized each function, you can then summarize the functionality of the entire file at the top of the file.

Your changes must still pass both the linter and the test suite, so be sure to test your changes locally!

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.

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. If you’d like, you can also make use of branching and pull requests in your own repository to practice working with GitHub.

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 personal branch back to the class repository. Similar to the Issue, your PR title should mention the full path of the file you’ve 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.

There will be automated checks that run on your pull request to ensure you meet the requirements of this assignment. Some of them take a while to run, so be sure to check on your pull request periodically to ensure that all these actions pass and everything is working properly!

Test Suite Failures

If the tests are failing on GitHub but work locally, it may be caused by server overload. Re-running the failing GitHub Action 1-2 times will resolve this.

If all of the actions 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! ✅

Written Assignment (15 pts)¶

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

Grading¶

To receive full credit for this project, we expect: