From 9c4d9e10bf4bd29ac6b70a48480bd90f5c11e0f8 Mon Sep 17 00:00:00 2001
From: Stockton Jenkins <jsjenkins4@wisc.edu>
Date: Wed, 29 Jan 2025 00:22:52 -0600
Subject: [PATCH] Update projects.md
---
projects.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 102 insertions(+), 11 deletions(-)
diff --git a/projects.md b/projects.md
index c0c83cb..ffddc10 100644
--- a/projects.md
+++ b/projects.md
@@ -45,11 +45,103 @@ will indicate whether or now you have a partner (and if so, who).
Upon a valid a submission, we'll create a repo for you and your
partner (if any) on GitLab and email you a link.
+## Project Setup
+
+To clone your GitLab repository on a VM, you can run the following command:
+```bash
+git clone https://oauth2:$GITLAB_ACCESS_TOKEN@repo_url
+```
+
+where `repo_url` is the `https` url (minus `https://` at the beginning and `.git` at the end) found at your remote project on GitLab
+
+Ex:
+```
+git.doit.wisc.edu/cdis/cs/courses/cs544/s25/PROJECT/NET_ID
+```
+
+And where `$GITLAB_ACCESS_TOKEN` is a user-level defined access token. To create a user-level access token (only need to do this once), follow these steps:
+
+1. Go to GitLab's Access Token Settings:
+ - Log in to your GitLab account.
+ - Click on your profile picture in the top-left corner and go to Preferences.
+ - On the left-hand sidebar, click Access Tokens.
+2. Create a New Access Token:
+ - Name: Give your token a descriptive name (e.g., "CS 544 Access Token").
+ - Expires at: Optionally, set an expiration date for the token (i.e. some time after the semester ends).
+ - Scopes: Choose the appropriate scopes based on your use case. Here are some common ones:
+ - `api`: Full access to the API, including project and repository management.
+ - `read_repository`: Allows read access to repositories (e.g., cloning).
+ - `write_repository`: Allows pushing to repositories.
+3. After selecting the desired scopes, click Create personal access token.
+4. Copy the Token:
+5. After creating the token, GitLab will display it once. Copy it and store it on your machine as an `env` variable:
+
+```bash
+nano ~/.bashrc
+```
+
+Write contents to file:
+```bash
+GITLAB_ACCESS_TOKEN="YOUR_TOKEN_GOES_HERE"
+```
+
+Reload shell (if applicable):
+```bash
+source ~/.bashrc
+```
+
+You can double check that the `env` variable was saved with:
+```bash
+echo $GITLAB_ACCESS_TOKEN
+```
+
+### Environment
+If one does not already exist for your project, create a `venv`:
+```bash
+python3.10 -m venv venv
+source venv/bin/activate
+```
+
+Note that if the above command fails, you may need run the following:
+
+```bash
+sudo apt install python3-venv
+```
+
+and use `python3` instead of `python3.10` when creating your `venv`.
+
+### Autograder
+We have developed a CLI to run the autograder for your projects. To use it, be sure to be in your `venv` in the terminal. Simply install using:
+```bash
+pip install -r requirements.txt
+```
+If the installation was successful, you will be able to run `autobadger` as a command in the terminal:
+```bash
+autobadger --info
+```
+This will output something like:
+```text
+Welcome to Autobadger!
+Current Version: [version]
+Usage: autobadger [--project PROJECT (p1-p8)] [--stdout STDOUT (print|json)]
+```
+
+Note that we will be updating the `autobadger` CLI throughout the semester to handle new projects and bug fixes. Be sure to install the latest version with each new project. If we ever need to release changes during a project, we will make an announcement in Canvas and share the latest version.
+
+To update the version, you can the following (again, inside your `venv`):
+```bash
+pip install -r requirements.txt --force-reinstall
+```
+
+### Read-Only Files
+
+Do NOT touch or edit `submit.sh`, `.gitlab-ci.yml` in your repository. These files are used to automate grading. Editing them could hinder your ability to submit properly.
+
## Submission
-You'll submit by pushing to your GitLab project repo. Be
-carefull not to push after the deadline unless your intention is to
-submit late (see policy below).
+Whenever you push to `main`, we determine that as a "submission" and run `autobadger` on your `main` branch. We then push our results to your repository under `Issues`. This issue will contain the contents of `autobadger` as well as some other metadata and notes. This *should* have the same output as if you were to run it locally. If anything seems terribly wrong, please reach send your [assigned TA](https://docs.google.com/spreadsheets/d/1HwI0o3IE97AWe_P_sKRPrUITPPGEdvsLzfEKcrP8NrU/edit?usp=sharing) with a link to your GitLab issue.
+
+> **NOTE**: Be carefull not to push after the deadline unless your intention is to submit late (see policy below).
* projects have four parts; for notebooks, use big headers to divide your work into the four parts ("# Part 1: ...")
* for question based project work, (Q1, Q2, etc), include comments like ("# Q1: ...") before the answers
@@ -61,20 +153,19 @@ submit late (see policy below).
The general rule is no submissions >3 days late. Each day late suffers a 10% penalty (so a 90% submission that is 2 days late gets 70%).
-Common exceptions, and who to ask:
-- Illness: you can **ask your TA** to override the late penalty, but they cannot give more than 3 days. To qualify, you share a link to your repo; your commit history should show you made a substantial start on the project at least 3 days prior to the deadline
-- Busyness: same policy as illness (you might be unusually busy due to travel, extracurriculars, other courses, etc). This shouldn't happen more than a couple times a semester
-- McBurney accomodations: **email your instructor** a proposed policy for the semester (we can discuss again if your situation changes during the semester)
+To qualify for a **waiver** of the late, you must have passed at least **2** tests in the `autobadger`. That means we should be able to see at least **2** tests pass when we look under `Issues` of your GitLab repository.
+
+> **NOTE**: A waiver does NOT extend the 3-day hard deadline, but it would waive the 10%/day penalty.
+
+We will be able to keep track of your submissions and to determine downstream if you qualify for the late policy. As a result, we ask that you *do not* reach out to TAs or Tyler directly to request for a waiver of the late penalty (unless absolute extreme circumstances demand it).
-If you're working with a project partner who has the late penalty waived by a TA, that means it is waived for you as well, even if you don't have special circumstances yourself.
+> **NOTE**: McBurney accomodations: **email your instructor** a proposed policy for the semester (we can discuss again if your situation changes during the semester)
For other cases (falling very far behind, family emergencies, etc), **reach out to your instructor** to discuss possible accomodations.
### Resubmission Policy
-Resubmissions generally won't be allowed once projects have been
-graded, except in unusual situations, or when we made a mistake on our
-end (like a misleading specification).
+Resubmissions generally won't be allowed once projects have been graded, except in unusual situations, or when we made a mistake on our end (like a misleading specification).
### "Pre-grading" Policy
--
GitLab