merge with main

Author: IDzyre

_docs/developer/development_instructions/automated_grading.md

@@ -133,6 +133,16 @@ To do this:
    sudo systemctl stop submitty_autograding_worker
    ```
 
+   You can confirm that these jobs are no longer running:
+   ```
+   ps -ef | grep submitty_auto
+   ```
+
+   If the jobs did not all stop, you can run:
+   ```
+   ps -ef | grep submitty_auto | grep -v grep | awk '{print $2}' | xargs kill -9
+   ```
+
 2. Now, as the `submitty_daemon` user, from the primary machine, run the
    shipper manager and watch the output.
 

_docs/developer/getting_started/commit_to_PR_from_fork.md

@@ -18,10 +18,22 @@ the forked repository has granted the necessary permissions*.  This
 allows multiple developers to collaborate and finalize a PR for
 merging to the main branch.
 
+If you use Github Desktop or have the Github CLI installed, the simplest
+way to work on a fork is to click the **Code** dropdown on the PR's page
+on Github and checkout the PR from there. 
+
+![alt text](/images/fork-checkout.png)
+
 The instructions below are for command line use of git.
 
+1. **Before** you begin, confirm that your local main branch of Submitty is
+    up-to-date. Additionally, if the PR's branch is not up-to-date with Submitty's main,
+    there will be a button on its page on Github that you can press to update it.
+    You may need to resolve merge conflicts in the process of updating it.
+    
+    ![alt text](/images/update-branch.png)
 
-1.  First, from the PR on the Github website, find the name of the
+2.  From the PR on the Github website, find the name of the
     user + branch name.  It should be formatted something like this:
     ```
     contributorusername:contributor_branch_name
@@ -31,7 +43,7 @@ The instructions below are for command line use of git.
     The `fork_name` may simply be `Submitty`, or the author may have chosen to another name.
     
 
-2.  Next, make a local branch on your computer in your working repository
+3.  Next, make a local branch on your computer in your working repository
     with the proposed code changes. Here are the command lines
     (substitute the user, branch, and fork names we found above):
 
@@ -48,14 +60,14 @@ The instructions below are for command line use of git.
     ```
 
 
-3.  This has made a local branch named
+4.  This has made a local branch named
     `contributorusername-contributor_branch_name`.  Go ahead and test
     and review the PR and make code edits and new commits to your
     local branch as needed.
 
 
 
-4.  In order to push the changes to the contributor's fork (and the PR
+5.  In order to push the changes to the contributor's fork (and the PR
     on Github from the fork), you will specify the upstream to be the
     contributor's fork:
 
@@ -93,7 +105,7 @@ The instructions below are for command line use of git.
     ```
 
 
-5.  Now once you are finished with your code changes, first commit them to
+6.  Now once you are finished with your code changes, first commit them to
     the local branch (named
     `contributorusername-contributor_branch_name`).
 
@@ -106,8 +118,14 @@ The instructions below are for command line use of git.
     *NOTE:  If you encounter a permissions error, it is possible that the external
     contributor didn't grant access for collaboration on the branch.*
 
-6.  Confirm that you can see the changes on the Github website for the PR.
+7.  Confirm that you can see the changes on the Github website for the PR.
 
+8.  NOTE that when you move on to work on another PR from a fork, you will need to
+    cleanup / unset the upstream before you can set it to another repository:
+
+    ```
+    git remote rm upstream
+    ```
 
 ---
 

_docs/developer/getting_started/make_a_pull_request.md

@@ -114,7 +114,7 @@ Be sure to read the [Suggestions for New Developers](/developer/getting_started/
       See also: [Installation Version Notes](/sysadmin/installation/version_notes)
 
     * To help ensure a title follows our standards, we utilize a
-    [GitHub workflow](https://github.com/Submitty/Submitty/blob/master/.github/workflows/pr_title.yml)
+    [GitHub workflow](https://github.com/Submitty/Submitty/blob/main/.github/workflows/pr_title_check.yml)
     for validation. Updating your PR title will immediately re-run the workflow, allowing you to edit 
     it till it does pass validation.
 

_docs/developer/getting_started/phpstorm.md

@@ -51,7 +51,7 @@ Under the `Mappings` tab, set the following:
 This step will configure PhpStorm to use the PHP CLI that is configured inside your vagrant machine.
 It is important to use this PHP installation as opposed to some other one as it ensures environment consistency among developers and production servers.
 
-Under PhpStorm settings, open `Languages & Frameworks` > `PHP`. Press the `...` button next to `CLI Interpreter` and, on the left list of the interpreters window, press the `+` and select `From Docker, Vagrant, VM, Remote...`.
+Under PhpStorm settings, open `PHP`. Press the `...` button next to `CLI Interpreter` and, on the left list of the interpreters window, press the `+` and select `From Docker, Vagrant, VM, Remote...`.
 Select `Vagrant` from the list of radio buttons.
 Then press `OK` to add the interpreter and `OK` to save the list of interpreters.
 
@@ -61,7 +61,7 @@ Open `Tools` > `Deployment...` > `Options`. Set `Upload changed files automatica
 
 ## Enable PHP debugging using xdebug
 
-Under PhpStorm settings, open `Languages & Frameworks` > `PHP` > `Debug`. In the pre-configuration steps, press `Validate` to open the configuration validator. Choose `Remote Web Server` and set the following:
+Under PhpStorm settings, open `PHP` > `Debug`. In the pre-configuration steps, press `Validate` to open the configuration validator. Choose `Remote Web Server` and set the following:
 
 - `Path to create validation script`: `<submitty repository root>/site/public`
 - `Deployment Server`: Use the SFTP connection you set up in the first step
@@ -91,7 +91,7 @@ Now you can browse the tables in the database window by expanding the tabs next
 
 ## Running PHPUnit tests
 
-Under PhpStorm settings, open `Languages & Frameworks` > `PHP` > `Test Frameworks`. Press the `+` button to add a testing configuration, using the `PHPUnit by Remote Interpreter` type. Choose the interpreter you configured in earlier steps. Then set:
+Under PhpStorm settings, open `PHP` > `Test Frameworks`. Press the `+` button to add a testing configuration, using the `PHPUnit by Remote Interpreter` type. Choose the interpreter you configured in earlier steps. Then set:
 
 - `PHPUnit Library`: `Use Composer autoloader`
 - `Path to script`: `/usr/local/submitty/GIT_CHECKOUT/Submitty/site/vendor/autoloader.php`
@@ -132,7 +132,7 @@ Press `OK` to save the run configuration. If you then `Debug` the configuration,
 
 During debugging, you may get decently upset at how often you step into magic methods and class loaders etc. There's an easy fix for this:
 
-Under PhpStorm settings, open `Languages & Frameworks` > `PHP` > `Debug` > `Step Filters`. Check `Skip magic methods` and add the following to `Skipped Methods`:
+Under PhpStorm settings, open `PHP` > `Debug` > `Step Filters`. Check `Skip magic methods` and add the following to `Skipped Methods`:
 
 - `app\views\AbstractView->__construct`
 - `app\models\AbstractModel->convertName`

_docs/developer/getting_started/vm_install_using_vagrant_apple_silicon.md

@@ -59,6 +59,8 @@ the installation process.
 
    $ brew install --cask vagrant
 
+   $ vagrant plugin install vagrant-timezone
+
    $ vagrant plugin install vagrant-qemu
    ```
    Note: It is possible that you may need to install Rosetta before installing vagrant. Run the following command to install Rosetta:

_docs/developer/troubleshooting/installation_troubleshooting.md

@@ -67,6 +67,7 @@ with no explanation, then there are a couple of things that may be going wrong:
     brew reinstall --cask vagrant
     vagrant plugin update
     vagrant box update
+    vagrant plugin install vagrant-timezone
     ```
 
     If you continue to have errors on Mac with `vagrant up` after
@@ -109,11 +110,25 @@ with no explanation, then there are a couple of things that may be going wrong:
   directories/repositories to clean up unwanted VMs.
 
   The following command can help locate misplaced repositories/VMs:
-
   ```
   vagrant global-status
   ```
 
+  If you see unnecessary VMs, you can clean them up with (replace
+  `1a2b3c4d` with the id of the VM you wish to destroy):
+  ```
+  vagrant destroy 1a2b3c4d
+  ```
+
+  If the command above does not successfully destroy and remove the VM from the
+  global-status list, you may see an error similar to: `The machine
+  with the name 'ubuntu-20.04' was not found configured for this
+  Vagrant environment.`  You can try to clean up these undestroyed VMs record by
+  running:
+  ```
+  vagrant global-status --prune
+  ```
+
 * If you might have old, forgotten VMs from previous OS versions
   hanging around it can be helpful to completely delete the `.vagrant`
   folder in your repository.  Also check to see if you have multiple
@@ -180,3 +195,35 @@ broadcast 192.168.56.255
 ```
 
 References and useful links: [https://gist.github.com/pjdietz/5768124](https://gist.github.com/pjdietz/5768124) and [http://christophermaier.name/2010/09/01/host-only-networking-with-virtualbox/](http://christophermaier.name/2010/09/01/host-only-networking-with-virtualbox/)
+
+
+## Guest Additions
+
+
+Submitty vagrant no longer uses Virtual Box Guest Additions.  If you
+see errors about version mismatch with Guest Additions, and if the VM
+hangs trying to update the version of Guest Additions to match the
+host version of Guest Additions, you may have old versions of the
+development process on your machine and may need to more completely
+uninstall and reinstall Virtual Box and Vagrant to reset your system.
+
+**NOTE: THESE ACTIONS WILL DELETE ALL VMS ON YOUR SYSTEM.**
+
+Some things to check:
+
+* From your main Submitty repository, e.g. `<SOMETHING>/GIT_CHECKOUT/Submitty/`
+  run `rm -rf .vagrant`
+
+  (you may need to put sudo in front)
+
+* Check all files on your filesystem for vagrant.  Run 'locate
+  vagrant' and remove any old library / installation files you see.
+  E.g.:
+
+  ```
+  rm /Applications/VirtualBox.app/Contents/MacOS/VBoxGuestAdditions.iso
+  rm -rf /opt/vagrant/
+  rm -rf /Users/MY_HOME_DIRECTORY/.vagrant.d/
+  rm -rf /Users/MY_HOME_DIRECTORY/.gem/specs/rubygems.org%443/quick/Marshal.4.8/vagrant-vbguest-0.31.0.gemspec
+  ```
+

_docs/instructor/autograding/docker_ui.md

@@ -7,7 +7,7 @@ Depending on your assignment, you may need to install new docker
 images on the system to perform autograding. You can do this via the
 Docker UI page available to instructors with the role `Faculty`.  To
 check if you have access, click on "My Profile" from the left sidebar.
-If you don't see "Access Level: Faculty", as your sysadmin to give you
+If you don't see "Access Level: Faculty", ask your sysadmin to give you
 this access.
 
 From the Docker UI page, you can see what capabilities are
@@ -19,7 +19,7 @@ disabled or there was an error associated with the updating of
 said machine. In the case of an error, there will be an area with
 the error within the System Wide Information section.
 
-### Adding Image
+### Adding Images
 
 To add an image to a capability, you must first select the
 capability to add to. Next you must provide a valid Docker

_docs/instructor/course_settings/rainbow_grades/customization_basics.md

@@ -26,12 +26,26 @@ It can contain the following:
 * ``"instructor_notes"``: Shows notes for early warnings, plagiarism, etc. only to the instructor
 * ``"grade_summary"``: Shows the overall score and score for each syllabus bucket (e.g. Homework)
 * ``"grade_details"``: Shows the score for each gradeable
+* ``"section"``: Show the students' registration section.
+* ``"messages"``: Show a text message at the top of the page.
 * ``"final_grade"``: Shows final grade letters and some statistics about the final grade distribution.
+* ``"manual_grade"``: Manually assign final grades to specific students.
 * ``"exam_seating"``: Shows exam seating assignments. To display the assignment on the Submitty course homepage,
   the instructor should make sure "Display Rainbow Grades Custom Message" is enabled in "Course Settings" on the Submitty
   course page.
 * ``"display_rank_to_individual"``: Shows each student's rank in the course, independent of section.
 
+  ```json
+    "display": [
+      "grade_summary",
+      "grade_details",
+      "section",
+      "messages",
+      "final_grade",
+      "manual_grade"
+    ]
+  ```
+
 * **field:** ``"display_benchmark"``  
   **type:** _array of strings_  
   **REQUIRED** if using ``"curve"`` in ``"gradeables"`` described below
@@ -43,6 +57,18 @@ It can contain the following:
    * ``"lowest_a-``, ``"lowest_b-"``, ``"lowest_c-"``, ``"lowest_d"``: Based on curves, the lowest scores that will earn
    the name of the benchmark. 
 
+  ```json
+    "display_benchmark": [
+      "average",
+      "stddev",
+      "perfect",
+      "lowest_a-",
+      "lowest_b-",
+      "lowest_c-",
+      "lowest_d"
+    ]
+  ```
+
 * **field:** ``"benchmark_percent"``  
   **type:** _associative array / mapping from string to float_  
   **REQUIRED** if using ``"curve"`` in ``"gradeables"`` described below, or if any grade-letter benchmarks are used in ``"display_benchmark"`` above.
@@ -51,6 +77,16 @@ It can contain the following:
   necessary to obtain that grade. For example to require an 82% for an A-, there should be an entry in the ``"benchmark_percent"`` array:
   ``"lowest_a-": 0.82``
 
+  To display all benchmarks, include the following:
+  ```json
+    "benchmark_percent": {
+      "lowest_a-": 0.9,
+      "lowest_b-": 0.8,
+      "lowest_c-": 0.7,
+      "lowest_d": 0.6
+    }
+  ```
+
 * **field:** ``"section"``  
   **type:** _associative array / mapping from string to string_  
   **REQUIRED**
@@ -60,34 +96,70 @@ It can contain the following:
   this array will be treated as invalid and ignored. These labels are only displayed
   on the instructor's `output.html`.
 
+  ```json
+    "section": {
+      "1": "1",
+      "2": "2",
+      "3": "3",
+      "4": "4",
+      "5": "5",
+      "6": "6",
+      "7": "7",
+      "8": "8",
+      "9": "9",
+      "10": "10"
+    }
+  ```
+
 * **field:** ``"messages"``  
   **type:** _array of strings_  
 
   These messages will be displayed at the top of the instructor summary and each
   student's individual Rainbow Grades report.
 
+  ```json
+    "messages": [
+      "Example message"
+    ]
+  ```
+
 * **field:** ``"final_cutoff"``  
   **type:** _associative array / mapping from string to float_  
   **REQUIRED** if using ``"final_grade"`` in ``"display"``
 
   Each grade letter that you want should be associated with the minimum overall semester score required to get that grade.
-  This array is unrelated to benchmarks.
+  This array is unrelated to benchmarks. For example:
+
+  ```json
+  "final_cutoff" : {
+    "A": 93.0,
+    "A-": 90.0,
+    "B+": 87.0,
+    "B": 83.0,
+    "B-": 80.0,
+    "C+": 77.0,
+    "C": 73.0,
+    "C-": 70.0,
+    "D+": 67.0,
+    "D": 63.0
+  }
+  ```
 
 * **field:** ``"manual_grade"``  
-  **type:** _associative array / mapping from string to associative array_  
+  **type:** _array of associative arrays_  
 
-  For each student that you want to assign a manual grade to, their id must
-  be mapped to an associative array with a field ``"grade"`` mapped to a string
-  with the letter grade you want to give them, and ``"note"`` containing any note
-  about the adjustment. The note is only visible to the instructor. For example, 
+  For each student that you want to assign a manual grade to, add an item to
+  ``"manual_grade"`` with fields ``"user"``, ``"grade"``, and ``"note"`` containing
+  any note about the adjustment. The note is only visible to the instructor. For example, 
   to give user ``smithj`` a grade lettter of ``D`` with a reason of 
   ``"Put in extraordinary effort."``:
 
   ```json
-  "smithj" : {
+  "manual_grade" : [{
+     "user":"smithj",
      "grade": "D",
      "note": "Put in extraordinary effort."
-  }
+  }]
   ```
 
 * **field:** ``"warning"``