Merge branch 'main' into sysadmin-note-http2

Author: cjreed121

Gemfile.lock

@@ -1,7 +1,7 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.4.2)
+    activesupport (7.0.7)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -14,7 +14,7 @@ GEM
     coffee-script-source (1.11.1)
     colorator (1.1.0)
     commonmarker (0.23.8)
-    concurrent-ruby (1.2.0)
+    concurrent-ruby (1.2.2)
     dnsruby (1.61.9)
       simpleidn (~> 0.1)
     em-websocket (0.5.3)
@@ -96,7 +96,7 @@ GEM
       typhoeus (~> 1.3)
       yell (~> 2.0)
     http_parser.rb (0.8.0)
-    i18n (1.12.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     jekyll (3.9.3)
       addressable (~> 2.4)
@@ -220,7 +220,7 @@ GEM
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    minitest (5.17.0)
+    minitest (5.19.0)
     nokogiri (1.14.1)
       mini_portile2 (~> 2.8.0)
       racc (~> 1.4)

README.md

@@ -41,8 +41,8 @@ by running:
    ```
 
    * _NOTE: During the install, it may hang up when installing the
-     dependency ``nokogiri``.  Don't worry: press enter and it should
-     continue.
+     dependency ``nokogiri``.  Don't worry: continue waiting. If it still is stalling
+     here, press enter and it should continue._
 
 
    * _NOTE: If an error is thrown during the installation process you

_docs/developer/development_instructions/index.md

@@ -55,8 +55,9 @@ Please also see [Installation Version Notes](/sysadmin/installation/version_note
 ## Website and Bin Script Changes
 
 * If you have only made minor or modest visual changes to website
-  (e.g., the html, css, twig, or php files), or other files in the
-  `site` folder, you can apply those changes by running this shortcut:
+  (e.g., the html, css, twig, or php files), other files in the `site`
+  folder, or translation files in the Localization repository, you can
+  apply those changes by running this shortcut:
 
   ```
   submitty_install_site
@@ -124,9 +125,7 @@ be able to reload the website and see the update.
   See also: [PhpStorm configuration instructions](/developer/getting_started/phpstorm)
 
 
----
-
-## Clearing Your Browser Cache
+### Clearing Your Browser Cache
 
 
 * If the JavaScript files have changed and there are errors or you do not see the
@@ -162,6 +161,9 @@ include more significant Submitty source code changes, it will likely
 be necessary to conduct a more complete update and reset re-set of all
 of the Submitty source code.
 
+
+
+
 * In these cases, run this shortcut in the vagrant terminal:
 
    ```
@@ -186,9 +188,12 @@ of the Submitty source code.
    sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh clean
    ```
 
----
 
-## Autograding Development
+Note: The above commands will also apply any necessary system and
+database [Migrations](/developer/development_instructions/migrations).
+
+
+### Autograding Development
 
 In addition to the `submitty_install` command above, if you modify an
 autograding configuration, you'll probably need to:
@@ -197,7 +202,6 @@ autograding configuration, you'll probably need to:
 
 * [Batch Regrade Homeworks](/instructor/batch_regrade_submissions) already submitted to those gradeables.
 
-
 ---
 
 ## System Clock Testing & Troubleshooting
@@ -264,7 +268,8 @@ these changes.
 * If you've changed the script to create a new course
   (`create_course.sh`), or the schema for the master database
   (`submitty_db.sql`), or the schema for the course databases
-  (`course_tables.sql`), we need to delete all courses, and recreate
+  (`course_tables.sql`), or you changed student/gradeable data
+  we need to delete all courses and recreate
   the course databases, users, and sample submission uploads.
 
   _NOTE: Make sure you are not be connected to any DBs (e.g., through
@@ -283,9 +288,12 @@ these changes.
   missing the hundreds of sample student submissions present in the
   full installation.
 
-  See also: [Database Migrations](/developer/development_instructions/migrations)
+
+  NOTE: This command will also have to be run twice a year on July 1st and January 1st when the test semester will change from fall to spring or vice versa.
 
 
+  See also: [Sample Course Data](/developer/development_instructions/sample_data)
+
 ---
 
 ## Complete System Re-Installation
@@ -322,3 +330,21 @@ these changes.
   also destroy the databases, and any grading configuration or grading
   work that has been done._
 
+---
+
+## Virtual Machine Recovery using Snapshots
+
+In the event of a non-recoverable error while working on Submitty the last resort is to, perform a fresh `vagrant up`. However, this process can be time-consuming. To avoid such situations and save time, it is highly recommended to take a snapshot when you first set up your Vagrant environment by following the tutorial links provided below:
+
+* [Virtual Box](https://www.youtube.com/watch?v=Kl-Qc6N9znw)
+
+* [VMWare](https://www.youtube.com/watch?v=DQutP_-2j3g)
+
+* [Vagrant](https://developer.hashicorp.com/vagrant/docs/cli/snapshot)
+
+By taking a snapshot at this initial stage, you can later revert to this saved state if needed, ensuring a quick recovery. Once you have restored the snapshot, you can then proceed with the following steps:
+
+1. Launch the virtual machine using `vagrant up`.
+2. Access the virtual machine with `vagrant ssh`.
+3. Run `submitty_install` command to conduct a more complete update and reset of all of the Submitty source code.
+

_docs/developer/development_instructions/localization.md

@@ -0,0 +1,139 @@
+---
+title: Localization / Language Support
+category: Developer > Development Instructions
+redirect_from:
+  - /developer/migrations
+---
+
+
+The goals of localization or internationalization include the
+translation of the website into multiple languages, to increase the
+accessibility of Submitty to users in all locales or regions.
+
+To contribute to Submitty's localization and translation efforts,
+follow these steps to update Twig templated files and provide
+translations for various text elements on the website.
+
+---
+
+## Server Language Specification
+
+By default, all Submitty pages will display in English based on the
+`en_US` locale.  To modify the server default setting, the system
+administrator should edit the
+`/usr/local/submitty/config/submitty.json` file and add this line, e.g.:
+
+```
+    "default_locale": "fr_FR",
+```
+
+to specify an alternate locale.
+See also [Php Locale class](https://www.php.net/manual/en/class.locale.php).
+
+---
+
+## Individual Language Specification
+
+Each individual user can specify their own preferred locale if they do
+not wish to use the server default.  Navigate to "My Profile" and
+choose the desired language and region settings.
+
+![](/images/student/user_profile_specify_locale.png) 
+
+The dropdown menu will include all locales for which any translation
+is available in the
+[Localization](https://github.com/Submitty/Localization/tree/main/lang)
+repository.  Where translation to the requested language is
+incomplete, the `en_US` locale will be used.
+
+---
+
+## Prepare a Website Page for Translation
+
+Submitty uses the Twig template engine to manage html source code with
+Php.  Checkout the [Submitty source
+code](https://github.com/Submitty/Submitty) and locate the specific
+`.twig` template file(s) associated with the webpage that you would
+like to update.
+
+
+Identify an untranslated English plain text string in the Twig source
+code, for example:
+
+```
+<p>Text in the page I will translate</p>
+```
+
+
+And replace that text string with the following syntax:
+
+```
+<p> { { localize("Page_Description.Text_To_Translate", "Text in the page I will translate") } } </p>
+```
+
+The `localize` function requires two arguments:
+
+* The first argument is the hierarchical tag or label, separated by
+  one or more dots.  The hierarchy should begin with the name of the
+  page, and intuitively name and organize/group all phrases that
+  appear on that page.  The first part represents the role or purpose
+  of the page, while the second (and later) parts describes the text
+  you're translating. Use underscores to replace spaces in this part.
+  Avoid using apostrophes, quotes, accents, and other special
+  characters.
+
+* The second argument is the original English text that will be
+  displayed on the website if a translation in the user's language is
+  not available.
+
+
+Make a [pull request](/developer/getting_started/make_a_pull_request)
+with your proposed changes.
+
+---
+
+## Updating the en_US.json Phrase File
+
+When Twig files are edited to prepare or update one or more pages for
+translation, these pages will be reviewed and merged.
+
+When a new release/version of the Submitty source code is published
+with changes to one or more `.twig` files, **[TODO]** the
+[`en_US.json` file in the Localization repository](https://github.com/Submitty/Localization/blob/main/lang/en_US.json)
+will be automatically updated.
+
+---
+
+## Adding Translations to the Localization Repository
+
+Once the pull request is merged and a new version of Submitty is
+released, checkout the [Localization](https://github.com/Submitty/Localization/tree/main/lang)
+repository and navigate to the `Localization/lang` directory.
+
+If a JSON file for the language you're translating to isn't available,
+create one. The file name format is as follows:
+```
+<language_code>_<country_code>.json
+```
+
+Copy the content of the en_US.json file and paste it into the newly
+created or existing JSON file.
+
+Edit the JSON file by translating the "Text in the page I will
+translate" text within the "Page_Description" section.  The JSON file
+format should resemble the following:
+
+```
+  {
+    "Page_Description": {
+      "Text_To_Translate": "Translated text for the page"
+    }
+  }
+```
+
+You should test your translation by following the
+[Development Instructions](/developer/development_instructions/index#incremental-development-updates).
+
+When you are finished, submit a pull request to the Localization
+repository with your new and/or modified JSON files. 
+

_docs/developer/development_instructions/sample_data.md

@@ -0,0 +1,76 @@
+---
+title: Sample Courses Data
+category: Developer > Development Instructions
+redirect_from:
+  - /developer/development_instructions/sample_data
+---
+
+As a developer, there are 5 sample courses:
+- **BLANK**
+    - Empty course.
+- **DEVELOPMENT**
+    - All files from `/more_autograding_examples/`, which mostly tests autograding.
+    - Most new features that need gradeables to test them will be put here.
+- **SAMPLE**
+    - A simultation of a "live" course mid-semester with lots of students and lots of submissions. Tests features such as ta grading, due dates, categories, etc.
+    - For manual & automated website testing.
+- **TUTORIAL**
+    - All tutorial gradeables are in sequence, emphasizing one new feature as they grow in complexity.
+- **PLAGIARISM**
+    - Used to test Lichen plagiarism detection.
+    - This is not available by default. You must clone the [Lichen Test Data](https://github.com/Submitty/LichenTestData) repository locally to see this.
+
+---
+
+## Predefined Data
+
+Predefined data is set using files in `/.setup/data/` and the script `/.setup/bin/setup_sample_courses.py`.
+
+| Data | Location | 
+|------|----------|
+| Course Gradeables | `/.setup/data/courses` |
+| Forum Threads | `/.setup/data/forum` |
+| Polls | `/.setup/data/polls` |
+| Office Hours Queue | `/.setup/data/queue` |
+| Team Assignment | `/.setup/data/teams` |
+| Predefined Users | `/.setup/data/users` |
+
+---
+
+## Sample Courses Student Data
+
+Sample Courses Student Data is set using `.yml` files and the script `/.setup/bin/setup_sample_courses.py`.
+
+#### Predefined Users
+
+`setup_sample_courses.py` parses the yaml files in `.setup/data/users/`. If you want to know more about how to write the user yaml files, read `.setup/data/users.yml`, which explains all the options.
+
+#### Random Users
+
+`setup_sample_courses.py` also generates random users. Randomly generated users generate random family and given names, user ids based on the names chosen, random anonymous user ids, numeric ids, and pronouns. For more information, read the `generate_random_users` function in `setup_sample_courses.py`.
+
+Randomly generated students are the same in every build, unless you make changes to `setup_sample_courses.py` or related files. This is because the random seed is set to a specific value. This decision was to keep test cases consistent. However, if you make changes that utilize randomness, it may change the randomly generated students, thus making the test cases obsolete. 
+
+If you make changes that use/alter random number generation, you may need to 
+edit the following files:
+- Peer Review:
+    - `.setup/data/random/students.txt`
+    - `.setup/data/random/graders.txt`
+- Office Hours Queue:
+    - `.setup/data/queue/queue_data.json`
+- Discussion Forum:
+    - `.setup/data/forum/threads.txt`
+    - `.setup/data/forum/posts.txt`
+- Teams:
+    - `.setup/data/teams/sample_open_team_homework_teams.csv`
+        
+These files are manually written for a given set of users (the set is predetermined due to 
+the random's seed staying the same). If you make any changes that affects the contents of the 
+set these files will be outdated and result in failure of recreate_sample_courses.
+
+You may also need to edit test cases in Cypress, Selenium, etc. 
+
+---
+
+See also: [Re-Creating All Sample Course Data](/developer/development_instructions/index#re-creating-all-sample-course-data)
+