projects.md

# General Project Directions

## Collaboration/Conduct Guidance

Students may work alone or optionally work in groups of two.

**Code copying between students is not allowed in this course, except
between project partners.  Copying includes emailing, taking photos,
looking while typing line by line, etc.  Copying code then changing it
is still copying and thus not allowed.  Lock your compute when it's
not attended.**

**Partners**
* there should only be one submission repo for the team
* it's NOT OK to submit code from your partner that you didn't help write or understand

**Other Collaboration**
* you can talk about logic and help each other debug
* **no code copying**; for example, no emailing code (or similar), no photos of code, no looking at code and typing it line by line
* copying code then changing it is still copying and thus not allowed

**ChatGPT, Large Language Models, Interactive Tools**
* use of the tools is permitted, with proper citation
* a "chats" directory should contain screenshots or PDFs of any chats, in their entirety.  Name them as chat1.png, chat2.png, etc.  PDF and JPG formats are also permitted.

**Other Online Resources**
* you **may not** use any online resource intended to provide solutions specific to CS 544
* you **may** use other online resources, with proper citation
* add a comment in your code before anything you copied from such sources

## Compute Setup

For most projects, we'll use VMs provided by CSL.  See the directions
[here](csl-vm.md) about how to access it.  The first project will
involve some setup (like installing docker) on the VM.

For later projects, we'll share details about how to do use cloud
resources.

## Project Repository Creation

At the start of each project, you must submit the [partner
form](https://tyler.caraza-harter.com/cs544/s25/forms.html).  This
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

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
* each project will specify some specific files you need to commit (like a p1.ipynb or server.py); in addition to those, include whatever is needed (except data) for somebody to run your code

## Policies

### Late Policy

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%).

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).

> **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).

### "Pre-grading" Policy

We won't pre-grade work, so don't ask questions like "does this all
look good?" during office hours.  When grading many assignments, it's
natural we'll notice issues someone might miss during office hours.
We also don't have the staff time to effectively grade submissions
twice.

You can always ask more specific questions if you're looking for some reassurance, such as:

* "does X in the spec mean Y, or does it mean Z"
* "what would be a good way to test this function?"
* "would this plot be clearer with ????, or without it"
* "is this result supposed to be deterministic, or are there reasons it might be different for other deployments?"