Docs: Contribution Guide

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+## Overview
+<!-- Give a brief overview of the changes made in this PR -->
+
+## Details
+<!-- If you feel it is helpful, list the changes made -->
+
+- Bulleted list with explanations
+
+## Testing
+<!-- How did you test this? 
+     If you didn't do any testing, explain why -->
+- [ ] Added/updated unit tests
+- [ ] Tested edge cases
+- [ ] Manual testing (if needed)
+
+## Dependencies
+<!-- If this PR relies on other PRs not yet merged to main, 
+    mention and link them here. Delete if there are none.
+    If this is dependent on exactly _one_ PR, mark that as the
+    merge target of this PR. GitHub will automatically update
+    the merge target once the dependent PR is merged. -->
+
+## Future Work
+<!-- Discuss things that should be done in the future, 
+     or related work going on in other issues/PRs.
+     Delete this section if there is none. -->
+
+## Additional Notes
+<!-- Add any extra context or screenshots
+     Delete this section if there are none. -->

README.md

@@ -4,8 +4,8 @@ Autograder for [BYU CS 240 Chess project](https://github.com/softwareconstructio
 
 ## Development and Contributing
 
-This project relies on TAs like you to maintain and adapt the program! Come join the team!
-Check out the [Contribution Guide](https://github.com/orgs/softwareconstruction240/projects/1/views/1?pane=issue&itemId=84732654&issue=softwareconstruction240%7Cautograder%7C448) to learn how to effectively contribute as a part of the Autograder Development Team!
+This project relies on TAs like you to maintain and adapt the program. Come join the team!
+Check out the [Contribution Guide](docs/CONTRIBUTING.md) to learn how to effectively contribute as a part of the Autograder Development Team.
 
 Read the [Getting Started Guide](docs/getting-started/getting-started.md) to get the project set up on your machine for development.
 

docs/CONTRIBUTING.md

@@ -0,0 +1,293 @@
+# Contribution Guide
+
+Hello there! Welcome to the CS 240 Autograder Repo. If you're new to the
+Autograder Development team, we're glad to have you here. The CS 240
+Autograder relies on TAs like you to maintain and adapt the codebase
+for our professors and students.
+
+This document will give you all the info you need to know to successfully
+contribute to the best Autograder on campus!
+
+## Table of Contents
+- Welcome (You already read that)
+- [New Contributors [Start here if you're new]](#new-contributors)
+- [Guiding Principles](#guiding-principles)
+- [Development Pipeline](#development-pipeline)
+    - [1: Issues](#1-issues)
+        - [When to Create Issue](#when-to-create-an-issue)
+        - [Creating an Issue](#creating-an-issue)
+        - [Working on an Issue](#working-on-an-issue)
+    - [2: Branches](#2-branches)
+        - [Creating a Branch](#creating-a-branch)
+    - [3: Making Changes](#3-making-changes)
+        - [Writing Good Commit Messages](#writing-good-commit-messages)
+    - [4: Pull Requests](#4-pull-requests)
+        - [Creating a Pull Request](#creating-a-pull-request)
+        - [Scope of a Pull Request](#scope-of-a-pull-request)
+        - [Reviewing a Pull Request](#reviewing-a-pull-request)
+        - [After Merging](#after-merging)
+- [About Page](#about-page)
+- [Reminder About Ownership](#reminder-about-ownership)
+
+## Guiding Principles
+
+- We are building production quality software that accurately generates academic scores for hundreds of students.
+- We are learning/practicing being participants on a small dev team.
+- We thrive with contributions from many diverse perspectives.
+- We serve fellow humans with divine purpose in this order:
+    1. The Lord
+    2. Class professors
+    3. Class students
+
+## New Contributors
+New to the Autograder Development team and not sure how to get
+started? Try this:
+
+1. Finish reading this document
+2. Get your dev environment set up by following the [Getting Started Guide](getting-started/getting-started.md)
+3. Review the Sequence/Class Diagrams (_Coming soon_)
+4. Look through some of the code, and try writing documentation for undocumented code
+5. Find a section of under-tested code and add some unit tests
+6. Take a look through the GitHub repo's [Issues](https://github.com/softwareconstruction240/autograder/issues) page
+   and find one you like, especially (but not limited to) ones labeled
+   ["good first issue"](https://github.com/softwareconstruction240/autograder/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
+
+Don't be afraid to submit a PR, and most importantly, just get sucked in!
+
+## Development Pipeline
+
+As a broad overview, all changes to the Autograder start as an issue. Each
+issue eventually gets a branch made to solve the issue. And each branch
+gets made into a pull request before becoming part of the main branch of code.
+
+### 1. Issues
+
+Issues help us track what needs to be done and who's working on what. You can pick an already
+existing issue to work on, or you can write your own.
+
+> [!TIP]
+> Ideally, you should first work on issues in the `On Deck` column of the
+[TA Project Board](https://github.com/orgs/softwareconstruction240/projects/1/views/9),
+> but you are welcome to pick any unassigned issue
+
+#### When to Create an Issue
+
+An issue generally represents "a single goal or task." Discussion and decisions about how to accomplish the task (and
+even if the task should be done) happens here. Usually, an issue should be fairly narrow in scope, so that it can be
+resolved with a single Pull Request (PR).
+
+Even when you're not sure if the task should be done, or how to go about it, go ahead and create an issue. The issue
+might be closed, but now that decision has been discussed, and the reasons for it are saved somewhere central in case
+they are relevant in the future.
+
+#### Creating an Issue
+- Create the issue from the [TA Projects Board](https://github.com/orgs/softwareconstruction240/projects/1)
+    - Click "add item" at the bottom of the `Todo` list
+    - Type `#autograder` to connect the issue to the Autograder
+    - Type a title and hit enter
+- Use a clear, descriptive title that uses one of these prefixes (including the colon):
+    - `Backend:` server side changes
+    - `Frontend:` client (web) side changes
+    - `Fullstack:` for issues that require front and backend changes
+    - `Docs:` changes to documentation (either markdown files or JSDocs/JavaDocs)
+    - `Tests:` adding or modifying tests
+    - `Dev:` changes to enhance the Autograder development experience
+- Provide a clear and complete PR description. Consider using the following sections:
+    - **Overview**: The two sentence of the key problem.
+    - **Discussion**: A brief history of the context or arguments related to the issue.
+      Provide enough context so others can understand the purpose.
+    - **Proposal**: Suggested ways the problem could be approached, solved, or implemented.
+      Include specific file/class/method names as appropriate.
+    - **Related Work**: Links to related issues, PRs, or other documentation.
+- Add labels as appropriate using the built-in picker.
+- Remember: Issues should be narrow in scope.
+
+#### Working on an Issue
+- Assign the issue to yourself before beginning work (this is how we know
+  who is working on what, and gives you a sort of ownership over the issue)
+- Create a new branch ([more info here](#2-branches))
+- If you find a new issue, file it separately (don't mix concerns)
+- Leave a comment from time to time with updates on your progress
+
+### 2. Branches
+Branches in `git` allow us to all work on separate things in the same codebase.
+You will do all your work in a branch.
+
+#### Creating a branch
+Create the branch directly from the issue so your work is linked.
+
+- Always branch from `main`
+    - (exceptions exist if you know what you're doing)
+- Use descriptive names that reflect what you're working on:
+    - `add-late-submission`
+    - `admin-display-verification-status`
+    - `server-communicator`
+    - `extract-service-logic-from-controllers`
+- If the issue name is clear and concise, the default branch name from clicking "Create a branch" from the issue page is
+  also fine. It usually looks something like `488-fullstack-add-code-coverage-for-unit-tests`
+- Use kebab-case (lowercase with hyphens)
+- Keep names concise but clear
+- One branch per issue (don't mix different features/fixes)
+
+### 3. Making Changes
+Now that you have a branch, you can start to code! Hurray! 🎉
+Here are important guidelines to follow:
+
+- Review and follow the Style Guide (_Coming Soon_)
+- Write tests for your code. All new features and functionality should have tests demonstrating correctness
+    - Update existing tests if you change functionality
+    - _New contributors: A great way to better understand the codebase is to try writing tests for existing code_
+- Keep commits focused and meaningful
+    - Each commit should represent one logical change
+    - Write clear commit messages that describe that change ([See guidelines](#writing-good-commit-messages))
+    - Commit frequently
+- Update documentation as you go
+    - Add JSDoc/JavaDoc comments to new code
+        - _New contributors: Another great way to learn the codebase is to document existing code_
+    - Update repo Markdown docs if needed
+    - Code should for the most part be self-documenting. If not, make sure to add inline comments
+- Push your code to GitHub at the end of each coding session. This lets other team members see how you're doing
+
+#### Writing Good Commit Messages
+- Start with an imperative statement that describes what the commit does:
+    - `add late submission validation`
+    - `fix grade calculation bug`
+    - `update setup instructions`
+    - `remove unused imports`
+    - `refactor test runner`
+    - `document API endpoints`
+- Use lowercase letters
+- Keep it concise but clear (aim for under 50 characters)
+- Bad examples:
+    - `changes` (too vague)
+    - `Added new feature` (past tense)
+    - `WIP` (uninformative)
+    - `Fix stuff` (too vague)
+
+For bigger changes, you can add more details after the first line (leave a blank line between the first
+line and the extra details).
+
+> [!TIP]
+> A good commit message lets other developers know what changed without having to look at the code!
+
+### 4. Pull Requests
+Pull requests are how you get your changes merged into the codebase.
+You create a pull request once you feel your changes are ready for review by other devs.
+You can also create a draft pull request if you would like some feedback on your code before then.
+
+![Pull Request Lifecycle Overview](https://docs.github.com/assets/images/help/repository/branching.png)
+
+#### Creating a Pull Request
+- Make sure you have pushed all changes to GitHub first
+- The title of your pull request should be simple, concise, and descriptive
+    - It should have a prefix just like an issue
+    - It can be basically the name of the branch
+        - Issue: `Frontend: refactor all server calls to one place`
+        - Branch: `refactor-server-calls-to-one-place`
+        - Pull Request: `Frontend: refactor server calls into ServerCommunicator`
+    - Ensure the PR
+      is [linked to the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)
+      it resolves, if any
+- Fill out the Pull Request template with enough detail for others to understand what
+  changed without having to read all the new code.
+- Make sure all GitHub actions pass:
+    - Your pull request will be blocked from merging if all tests don't pass
+- Move the connected issue into the `PR Submitted` column on the
+  [TA Project Board](https://github.com/orgs/softwareconstruction240/projects/1/views/9)
+- Request a review from other Autograder developers
+    - If you're changing an existing system, request a review from the developer that
+      wrote it initially, or is most familiar with that system
+    - You can request multiple reviewers, but you're only required to get one approval to merge
+
+#### Scope of a Pull Request
+- Pull Requests should represent a complete, reviewable unit of work
+- In most cases, a pull request from one issue
+    - Multiple issues in one PR are fine and encouraged when they depend on each other, or form a cohesive change
+- While there's no strict size limit, consider breaking up very large changes if:
+    - They touch multiple unrelated areas
+    - They're becoming difficult to review
+    - They could logically be shipped separately
+
+> [!TIP]
+> A good PR represents a complete feature or fix, but shouldn't try to solve everything at once!
+
+#### Reviewing a Pull Request
+A crucial part of this process is the code review. The repo has been set up so that _**no changes may be merged
+into main without the review of at least one other developer.**_ If someone has requested a review from you, please
+take some time to help out and ensure the Autograder has quality code.
+
+**As a Reviewer**
+- Look for:
+    - Code quality and style guide compliance
+    - Test coverage
+    - Potential bugs or edge cases
+    - Documentation completeness
+- Checkout the branch on your local machine and do some manual testing
+    - Specifically verify new/changed systems work. Try breaking it.
+    - Generally check other systems still work and haven't been broken
+        - (Student submissions on test student is most important)
+- Be constructive and kind in your feedback. We're all learning here
+- If changes are needed:
+    - Be specific about what needs to change
+    - Explain why the change is needed
+    - Suggest how to make the change if possible
+- Approve the PR when you're satisfied with all changes
+
+**As a Pull Request Author**
+- Respond to reviewer comments promptly
+- Be open to feedback and suggestions
+- Explain your decisions when asked
+- Make requested changes or explain why they shouldn't be made
+- Mark conversations as resolved _only_ once you have addressed the concern
+- Re-request review from key individuals
+- Thank reviewers for their time
+
+> [!IMPORTANT]
+> Once the pull request is approved and ready to merge, it is the responsibility and privilege of the author
+> (not the reviewer) to merge the request.
+
+> [!NOTE]
+> Once a pull request is merged to main, it does not immediately deploy to the live Autograder. Changes will
+> not be reflected in the live system until the head Autograder developer releases a new version of the system.
+
+#### After Merging
+Congrats! You just added code to the Autograder!
+
+Make sure you move your issue on the [TA Project Board](https://github.com/orgs/softwareconstruction240/projects/1/views/9)
+to the `Done` column. This will happen automatically if the PR was linked to issue it resolves when the PR was merged.
+
+Celebrate!
+
+## About Page
+A lot of time and effort goes into developing and maintaining the Autograder. Thank you!
+
+If you're new to the team, add yourself to the Autograder's [About Page](../src/main/resources/frontend/src/components/AboutPage.vue).
+(You can see the live one by doing the Konami Code anywhere on the Autograder front end.)
+
+Fill this component out and add it to the bottom of the current list of developers:
+```vue
+<AboutPagePerson
+  name=""
+  url=""
+  tenure=""
+  contributions=""
+  fa-icon=""/>
+```
+Most TAs just link to their GitHub profile on their URL.
+
+Tenure should indicate when you worked as a CS 240 TA, not just as an Autograder Developer.
+
+Write a short sentence describing your work on the Autograder. You can update this in the future as you make more contributions.
+
+FA-icon is a font-awesome icon. Search through [Font Awesome's free icon collection](https://fontawesome.com/search?o=r&m=free)
+and choose one to represent you.
+
+## Reminder About Ownership
+As BYU employees writing code for our job as TAs, all code you contribute becomes the
+intellectual property of Brigham Young University.
+
+> Pursuant to law and university policy, **any work** (whether a Technical Work or a Creative Work) prepared by
+> University Personnel within the scope of their employment, without an express agreement specifying otherwise,
+> **is work for hire owned by the university**.
+>
+> — [BYU Intellectual Property Policy](https://policy.byu.edu/view/intellectual-property-policy) (emphasis added)

docs/getting-started/getting-started.md

@@ -1,5 +1,8 @@
 # Getting Started
 
+> [!TIP]
+> Read through the [Contribution Guide](../CONTRIBUTING.md) before making contributions to the project.
+
 ## Pre-requisites
 
 > [!IMPORTANT]

src/main/resources/frontend/src/components/AboutPage.vue

@@ -114,6 +114,10 @@ onUnmounted(() => {
           tenure="Jan 2024-Aug 2024"
           contributions="Wrote some systems that did pre-compiling verification of student code"
           fa-icon="fa-solid fa-face-grin-squint-tears"/>
+        <!--
+        New Autograder Developers!
+        Add yourself to the list right above this comment
+        -->
       </div>
 
       <InfoPanel id="about">