diff --git a/.bundle/config b/.bundle/config new file mode 100644 index 00000000..ee5bb423 --- /dev/null +++ b/.bundle/config @@ -0,0 +1,3 @@ +--- +BUNDLE_PATH: "vendor/bundle" +BUNDLE_FROZEN: "false" diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..f59c6ebf --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,12 @@ +version: 2 +updates: +- package-ecosystem: bundler + directory: "/" + schedule: + interval: daily + time: "10:00" + open-pull-requests-limit: 10 + versioning-strategy: increase + commit-message: + prefix: "[Dependency] " + prefix-development: "[DevDependency] " diff --git a/.github/workflows/pr_title_check.yml b/.github/workflows/pr_title_check.yml new file mode 100644 index 00000000..a84972e8 --- /dev/null +++ b/.github/workflows/pr_title_check.yml @@ -0,0 +1,20 @@ +name: 'Submitty PR Title Check' +on: + pull_request: + # check when PR + # * is created, + # * title is edited, and + # * new commits are added (to ensure failing title blocks merging) + types: [ opened, reopened, edited, synchronize ] + +jobs: + title-check: + runs-on: ubuntu-latest + steps: + # + # pull request titles format rules here: + # https://submitty.org/developer/getting_started/make_a_pull_request + # + # [:] + # + - uses: submitty/action-pr-title@main diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 00000000..769f5f6f --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,34 @@ +name: Ruby + +on: + push: + branches: [ '*' ] + pull_request: + branches: [ '*' ] + +jobs: + test: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + + - name: Get Ruby version + id: rubyversion + run: echo "::set-output name=version::3.2" + + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ steps.rubyversion.outputs.version }} + bundler-cache: true + + - name: Install dependencies + run: bundle install + + - name: Build Site + run: bundle exec jekyll build + + - name: Check Links + run: bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external diff --git a/.gitignore b/.gitignore index 5b879714..10e1b48a 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,7 @@ _site/ .sass-cache/ .jekyll-metadata *.iml -.idea/ \ No newline at end of file +.idea/ +*~ +.DS_Store +vendor/ diff --git a/Gemfile b/Gemfile index 3a2f6b66..576ad34e 100644 --- a/Gemfile +++ b/Gemfile @@ -1,11 +1,14 @@ +# This should be synced ocasionally with https://pages.github.com/versions/ source 'https://rubygems.org' -gem 'jekyll', '3.3.1' - group :jekyll_plugins do - gem 'jekyll-sitemap', '0.11.0' - gem 'jekyll-seo-tag', '2.0.0' - gem 'jekyll-feed', '0.7.2' + gem "github-pages", "232" end -gem 'wdm', '>= 0.1.0' if Gem.win_platform? \ No newline at end of file +gem 'wdm', '>= 0.1.1' if Gem.win_platform? + +gem "webrick", "~> 1.9" + +gem 'html-proofer', "~> 3.19.4" + +gem 'json' diff --git a/Gemfile.lock b/Gemfile.lock index b77dd667..d9e7420b 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,55 +1,300 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.4.0) + activesupport (7.1.3.4) + base64 + bigdecimal + concurrent-ruby (~> 1.0, >= 1.0.2) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + minitest (>= 5.1) + mutex_m + tzinfo (~> 2.0) + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + base64 (0.2.0) + bigdecimal (3.1.8) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.12.2) colorator (1.1.0) - ffi (1.9.14) - ffi (1.9.14-x64-mingw32) + commonmarker (0.23.10) + concurrent-ruby (1.3.3) + connection_pool (2.4.1) + csv (3.3.0) + dnsruby (1.72.2) + simpleidn (~> 0.2.1) + drb (2.2.1) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + execjs (2.9.1) + faraday (2.10.1) + faraday-net_http (>= 2.0, < 3.2) + logger + faraday-net_http (3.1.1) + net-http + ffi (1.17.2-arm64-darwin) + ffi (1.17.2-x64-mingw-ucrt) + ffi (1.17.2-x86_64-linux-gnu) forwardable-extended (2.6.0) - jekyll (3.3.1) + gemoji (4.1.0) + github-pages (232) + github-pages-health-check (= 1.18.2) + jekyll (= 3.10.0) + jekyll-avatar (= 0.8.0) + jekyll-coffeescript (= 1.2.2) + jekyll-commonmark-ghpages (= 0.5.1) + jekyll-default-layout (= 0.1.5) + jekyll-feed (= 0.17.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.16.1) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.13.0) + kramdown (= 2.4.0) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.4) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.16.2, < 2.0) + rouge (= 3.30.0) + terminal-table (~> 1.4) + webrick (~> 1.8) + github-pages-health-check (1.18.2) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (>= 4, < 8) + public_suffix (>= 3.0, < 6.0) + typhoeus (~> 1.3) + html-pipeline (2.14.3) + activesupport (>= 2) + nokogiri (>= 1.4) + html-proofer (3.19.4) + addressable (~> 2.3) + mercenary (~> 0.3) + nokogiri (~> 1.13) + parallel (~> 1.10) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + http_parser.rb (0.8.0) + i18n (1.14.5) + concurrent-ruby (~> 1.0) + jekyll (3.10.0) addressable (~> 2.4) colorator (~> 1.0) + csv (~> 3.0) + em-websocket (~> 0.5) + i18n (>= 0.7, < 2) jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 1.1) - kramdown (~> 1.3) - liquid (~> 3.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) mercenary (~> 0.3.3) pathutil (~> 0.9) - rouge (~> 1.7) + rouge (>= 1.7, < 4) safe_yaml (~> 1.0) - jekyll-feed (0.7.2) - jekyll-sass-converter (1.5.0) + webrick (>= 1.0) + jekyll-avatar (0.8.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.2.2) + coffee-script (~> 2.2) + coffee-script-source (~> 1.12) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.5.1) + commonmarker (>= 0.23.7, < 1.1.0) + jekyll (>= 3.9, < 4.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 5.0) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-feed (0.17.0) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.16.1) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) sass (~> 3.4) - jekyll-seo-tag (2.0.0) - jekyll (~> 3.1) - jekyll-sitemap (0.11.0) - addressable (~> 2.4.0) - jekyll-watch (1.5.0) - listen (~> 3.0, < 3.1) - kramdown (1.13.1) - liquid (3.0.6) - listen (3.0.8) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.13.0) + gemoji (>= 3, < 5) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + json (2.13.2) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + logger (1.6.0) mercenary (0.3.6) - pathutil (0.14.0) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.24.1) + mutex_m (0.2.0) + net-http (0.4.1) + uri + nokogiri (1.18.9-arm64-darwin) + racc (~> 1.4) + nokogiri (1.18.9-x64-mingw-ucrt) + racc (~> 1.4) + nokogiri (1.18.9-x86_64-linux-gnu) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + parallel (1.24.0) + pathutil (0.16.2) forwardable-extended (~> 2.6) - rb-fsevent (0.9.8) - rb-inotify (0.9.7) - ffi (>= 0.5.0) - rouge (1.11.1) - safe_yaml (1.0.4) - sass (3.4.22) + public_suffix (5.1.1) + racc (1.8.1) + rainbow (3.1.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.3.4) + strscan + rouge (3.30.0) + rubyzip (2.3.2) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + simpleidn (0.2.3) + strscan (3.1.0) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + typhoeus (1.4.1) + ethon (>= 0.9.0) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unicode-display_width (1.8.0) + uri (0.13.0) + webrick (1.9.1) + yell (2.2.2) PLATFORMS - ruby - x64-mingw32 + arm64-darwin-22 + arm64-darwin-23 + arm64-darwin-24 + x64-mingw-ucrt + x86_64-linux DEPENDENCIES - jekyll (= 3.3.1) - jekyll-feed (= 0.7.2) - jekyll-seo-tag (= 2.0.0) - jekyll-sitemap (= 0.11.0) + github-pages (= 232) + html-proofer (~> 3.19.4) + json + webrick (~> 1.9) BUNDLED WITH - 1.14.5 + 2.5.6 diff --git a/README.md b/README.md index ea08c0ca..e26d2eca 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,139 @@ -# Submitty +# Submitty.org -This is the documentation website for [Submitty](http://submitty.org) the RPI Homework Submission Server. +This is the documentation website for [Submitty](http://submitty.org), +an open source course management, assignment submission, exam, and grading system. -![Submitty screenshot](images/Submission_Result_Buggy.png) -## Developers +To report issues for this repository, please file them under the +[Submitty/Submitty](https://github.com/Submitty/Submitty) repository. -Edition was built with [Jekyll](http://jekyllrb.com/) version 3.3.1, but should support newer versions as well. +## Local Development -Install the dependencies with [Bundler](http://bundler.io/): +### Prerequisites -~~~bash -$ bundle install -~~~ +To develop the site locally, you will need to get the following dependencies: -Run `jekyll` commands through Bundler to ensure you're using the right versions: +* [Ruby](https://www.ruby-lang.org/en/) +* [Bundler](https://bundler.io/) (`gem install bundler`) -~~~bash -$ bundle exec jekyll serve -~~~ +For Bundler, depending on your system, you may need to also install the +Ruby development headers (e.g. `ruby-dev`). On Ubuntu/Debian, +for example, this would be accomplished by doing `sudo apt-get install ruby-dev`. -## Editing +### Setup -Edition is already optimised for adding, updating and removing documentation pages in CloudCannon. +1. Clone the respository on your local machine, e.g., -### Documentation pages + ``` + git clone https://github.com/Submitty/submitty.github.io.git + ``` -* Add, update or remove a documentation page in the *Documentation* collection. -* Change the category of a documentation page to move it to another section in the navigation. -* Documentation pages are organised in the navigation by category, with URLs based on the path inside the `_docs` folder. + * _NOTE: We recommend placing the code in a directory/folder on your + machine without spaces, because some developers have experienced + errors with bundler when the full path contained spaces._ -### Change log -* Add, update or remove change log entries from your posts. -* Tag entries as minor or major in the front matter. +2. Use Bundler to install the dependencies. This can be accomplished +by running: + + ```bash + bundle install + ``` + + * _NOTE: During the install, it may hang up when installing the + 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 + may need to downgrade from 3.0 to use Ruby-2.7 and make sure this + is indeed the version that the Bundler is using and not another + one in a different directory._ + + +### Running the Site + +* To view the site locally, and the results of any changes you make, + you will want to use the `jekyll` commands through Bundler, namely + the `serve` sub-command, as shown below: + + ```bash + bundle exec jekyll serve + ``` + +* NOTE: If you have an error running on the default port (4000), you can specify an + alternate port, e.g. + + ```bash + bundle exec jekyll serve --port 4001 + ``` + +* If you wish to build the site locally instead of running it, you can do: + + ```bash + bundle exec jekyll build + ``` + + which will leave the results in a `_site` directory. + + +### Running the link checker + +GitHub Actions checks each pull request for broken links using the +[`htmlproofer`](https://github.com/gjtorikian/html-proofer) +package. If you wish to run `htmlproofer` locally, `cd` into the `submitty.github.io` +repository and run the command: +``` +bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external +``` + + +## Editing Content + +The site's content is defined with markdown files under the +[`docs/`](https://github.com/Submitty/submitty.github.io/blob/main/_docs) folder, where +then it's separated by a couple of high-level sections (student, instructor, +sysadmin, developer). For any new page, a new entry must be added to the +navigation manually (see below). The rendered markdown uses a variant of +[Github Flavored Markdown](https://github.github.com/gfm/). For every page, +it should have a front-matter block at the top of the file that has minimally: + +``` +--- +title: Page Title +--- +``` + +where this is used as the main header title on the page, as well as for the title +of the page in the browser. You should then not include a `# Page Title` +in the file, rather just start your content immediately after the front-matter block. + +### Navigation + +Editing the links on the navigation is done by editing +[`navtreedata.js`](https://github.com/Submitty/submitty.github.io/blob/main/navtreedata.js). +The structure of the file is that each level is a list of objects, where the object can have the following parts: + +* name __(required)__ +* link +* children + +Where if link is omitted, then name will be used where it will be lowercased +and spaced replaced with `_`. Children is then a list of objects of the +above structure. Currently, the site only supports three levels of nesting (sub-sub-children). ### Search * Add `excluded_in_search: true` to any documentation page's front matter to exclude that page in the search results. -### Navigation +## Forked from [Edition](https://github.com/CloudCannon/edition-jekyll-template) + +This repository was created via a fork of Edition, which is a product documentation theme for Jekyll created +by by [CloudCannon](http://cloudcannon.com/), the Cloud CMS for Jekyll. + -* Change `site.show_full_navigation` to control all or only the current navigation group being open. -# Built with [Edition](https://github.com/CloudCannon/edition-jekyll-template) +### Ruby Version Troubleshooting -Edition is a product documentation theme for Jekyll, see a [live demo](https://long-pig.cloudvent.net/). -Edition was made by [CloudCannon](http://cloudcannon.com/), the Cloud CMS for Jekyll. -Find more templates and themes at [Jekyll Tips](http://jekyll.tips/templates/). -Learn Jekyll with step-by-step tutorials and videos at [Jekyll Tips](http://jekyll.tips/). +In February 2024: +* https://ritviknag.com/tech-tips/ruby-versioning-hell-with-jekyll-&-github-pages/ \ No newline at end of file diff --git a/_config.yml b/_config.yml index 3db7772f..9f7a3037 100644 --- a/_config.yml +++ b/_config.yml @@ -31,16 +31,18 @@ social: permalink: pretty -gems: +plugins: - jekyll-sitemap - jekyll-seo-tag - jekyll-feed + - jekyll-redirect-from exclude: - Gemfile - Gemfile.lock - README.md - LICENCE + - vendor collections: docs: @@ -70,4 +72,4 @@ defaults: type: "posts" values: _comments: - type: Marks the impact of this release \ No newline at end of file + type: Marks the impact of this release diff --git a/_data/api_data.json b/_data/api_data.json new file mode 100644 index 00000000..154bcf89 --- /dev/null +++ b/_data/api_data.json @@ -0,0 +1,178 @@ +[ + { + "type": "POST", + "url": "/api/token", + "title": "Get Token", + "group": "Authentication", + "parameter": { + "fields": { + "Parameter": [ + { + "group": "Parameter", + "type": "String", + "optional": false, + "field": "user_id", + "description": "

User's unique ID.

" + }, + { + "group": "Parameter", + "type": "String", + "optional": false, + "field": "password", + "description": "

User's password.

" + } + ] + } + }, + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "token", + "description": "

Access token for the user.

" + } + ] + } + }, + "error": { + "fields": { + "Error 4xx": [ + { + "group": "Error 4xx", + "optional": false, + "field": "AuthenticationException", + "description": "

Could not login using that user id or password.

" + }, + { + "group": "Error 4xx", + "optional": false, + "field": "InvalidArguments", + "description": "

Cannot leave user id or password blank.

" + } + ] + } + }, + "examples": [ + { + "title": "Example usage:", + "content": "curl -d \"user_id=instructor&password=instructor\" -X POST http://localhost:1511/api/token", + "type": "curl" + } + ], + "version": "0.0.0", + "filename": "./site/app/controllers/AuthenticationController.php", + "groupTitle": "Authentication", + "name": "PostApiToken" + }, + { + "type": "GET", + "url": "/api/courses", + "title": "List Courses", + "group": "Courses", + "header": { + "fields": { + "Header": [ + { + "group": "Header", + "type": "String", + "optional": false, + "field": "Authorization", + "description": "

User's token.

" + } + ] + } + }, + "success": { + "fields": { + "Success 200": [ + { + "group": "Success 200", + "type": "Course[]", + "optional": false, + "field": "unarchived_courses", + "description": "

List of unarchived courses.

" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "unarchived_courses.semester", + "description": "

Semester of the course.

" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "unarchived_courses.title", + "description": "

Title of the course.

" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "unarchived_courses.display_name", + "description": "

Displayed name of the course.

" + }, + { + "group": "Success 200", + "type": "Course[]", + "optional": false, + "field": "archived_courses", + "description": "

List of archived courses.

" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "archived_courses.semester", + "description": "

Semester of the course.

" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "archived_courses.title", + "description": "

Title of the course.

" + }, + { + "group": "Success 200", + "type": "String", + "optional": false, + "field": "archived_courses.display_name", + "description": "

Displayed name of the course.

" + } + ] + } + }, + "version": "0.0.0", + "filename": "./site/app/controllers/HomePageController.php", + "groupTitle": "Courses", + "name": "GetApiCourses" + }, + { + "type": "POST", + "url": "/api/:semester/:course/reports/summaries", + "title": "Generate grade summary", + "group": "Courses", + "header": { + "fields": { + "Header": [ + { + "group": "Header", + "type": "String", + "optional": false, + "field": "Authorization", + "description": "

User's token.

" + } + ] + } + }, + "version": "0.0.0", + "filename": "./site/app/controllers/admin/ReportController.php", + "groupTitle": "Courses", + "name": "PostApiSemesterCourseReportsSummaries" + } +] diff --git a/_docs/developer/Install_common_errors.md b/_docs/developer/Install_common_errors.md deleted file mode 100644 index 0f783929..00000000 --- a/_docs/developer/Install_common_errors.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Troubleshooting -category: Developer -order: 2 ---- - -If you are having trouble being able to view the Submitty webpage after a ```vagrant up``` you might need to -modify the interfaces in your VM. To fix this: - -As root modify ```/etc/network/interfaces``` and add: - -``` -# The host-only network interface -auto eth1 -iface eth1 inet static -address 192.168.56.101 -netmask 255.255.255.0 -network 192.168.56.0 -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/) - ---- - -During the install of the various packages referenced on [Vm Install Using Vagrant](vm_install_using_vagrant), -you might have ran into a few errors along the way. Below are a few common errors, and what you can do to solve them. - -**Ubuntu Installation** - -The following errors were experienced and fixed on a Ubuntu 16.04 distribution. - -1. Ruby undefined method when running command (for vagrant version 1.8.1): - - ``` - sudo vagrant plugin install vagrant-vbguest - ``` - - Error message recieved: - - ``` - Installing the 'vagrant-vbguest' plugin. This can take a few minutes... - /usr/lib/ruby/2.3.0/rubygems/specification.rb:946:in `all=': undefined method `group_by' for nil:NilClass (NoMethodError) - from /usr/lib/ruby/vendor_ruby/vagrant/bundler.rb:275:in `with_isolated_gem' - from /usr/lib/ruby/vendor_ruby/vagrant/bundler.rb:231:in `internal_install' - from /usr/lib/ruby/vendor_ruby/vagrant/bundler.rb:102:in `install' - from /usr/lib/ruby/vendor_ruby/vagrant/plugin/manager.rb:62:in `block in install_plugin' - from /usr/lib/ruby/vendor_ruby/vagrant/plugin/manager.rb:72:in `install_plugin' - from /usr/share/vagrant/plugins/commands/plugin/action/install_gem.rb:37:in `call' - from /usr/lib/ruby/vendor_ruby/vagrant/action/warden.rb:34:in `call' - from /usr/lib/ruby/vendor_ruby/vagrant/action/builder.rb:116:in `call' - from /usr/lib/ruby/vendor_ruby/vagrant/action/runner.rb:66:in `block in run' - from /usr/lib/ruby/vendor_ruby/vagrant/util/busy.rb:19:in `busy' - from /usr/lib/ruby/vendor_ruby/vagrant/action/runner.rb:66:in `run' - from /usr/share/vagrant/plugins/commands/plugin/command/base.rb:14:in `action' - from /usr/share/vagrant/plugins/commands/plugin/command/install.rb:32:in `block in execute' - from /usr/share/vagrant/plugins/commands/plugin/command/install.rb:31:in `each' - from /usr/share/vagrant/plugins/commands/plugin/command/install.rb:31:in `execute' - from /usr/share/vagrant/plugins/commands/plugin/command/root.rb:56:in `execute' - from /usr/lib/ruby/vendor_ruby/vagrant/cli.rb:42:in `execute' - from /usr/lib/ruby/vendor_ruby/vagrant/environment.rb:268:in `cli' - from /usr/bin/vagrant:173:in `
' - ``` - - In order to solve this, you can patch vagrant's ruby bundler (solution taken from: [stackoverflow](https://stackoverflow.com/a/36991648/3646475)) - - Create a file named _vagrant-plugin.patch_: - - ``` - --- - lib/vagrant/bundler.rb | 3 ++- - 1 file changed, 2 insertions(+), 1 deletion(-) - - diff --git a/lib/vagrant/bundler.rb b/lib/vagrant/bundler.rb - index 5a5c185..c4a3837 100644 - --- a/lib/vagrant/bundler.rb - +++ b/lib/vagrant/bundler.rb - @@ -272,7 +272,6 @@ module Vagrant - - # Reset the all specs override that Bundler does - old_all = Gem::Specification._all - - Gem::Specification.all = nil - - # /etc/gemrc and so on. - old_config = nil - @@ -286,6 +285,8 @@ module Vagrant - end - Gem.configuration = NilGemConfig.new - - + Gem::Specification.reset - + - # Use a silent UI so that we have no output - Gem::DefaultUserInteraction.use_ui(Gem::SilentUI.new) do - return yield - ``` - - And run the following command to apply the patch: - - ``` - sudo patch --directory /usr/lib/ruby/vendor_ruby/vagrant < vagrant-plugin.patch - ``` - -2. zlib is missing; necessary for building libxml2 when running command: - - ``` - sudo vagrant plugin install vagrant-vbguest - ``` - - Error message recieved: - - ``` - Installing the 'vagrant-vbguest' plugin. This can take a few minutes... - Bundler, the underlying system Vagrant uses to install plugins, - reported an error. The error is shown below. These errors are usually - caused by misconfigured plugin installations or transient network - issues. The error from Bundler is: - - An error occurred while installing nokogiri (1.8.0), and Bundler cannot continue. - Make sure that `gem install nokogiri -v '1.8.0'` succeeds before bundling. - - Warning: this Gemfile contains multiple primary sources. Using `source` more than once without a block is a security risk, and may result in installing unexpected gems. To resolve this warning, use a block to indicate which gems should come from the secondary source. To upgrade this warning to an error, run `bundle config disable_multisource true`.Gem::Ext::BuildError: ERROR: Failed to build gem native extension. - - current directory: /home/user/.vagrant.d/gems/gems/nokogiri-1.8.0/ext/nokogiri - /usr/bin/ruby2.3 -r ./siteconf20170914-2709-1ddc8yn.rb extconf.rb - checking if the C compiler accepts ... yes - Building nokogiri using packaged libraries. - Using mini_portile version 2.2.0 - checking for gzdopen() in -lz... no - zlib is missing; necessary for building libxml2 - *** extconf.rb failed *** - Could not create Makefile due to some reason, probably lack of necessary - libraries and/or headers. Check the mkmf.log file for more details. You may - need configuration options. - - Provided configuration options: - --with-opt-dir - --without-opt-dir - --with-opt-include - --without-opt-include=${opt-dir}/include - --with-opt-lib - --without-opt-lib=${opt-dir}/lib - --with-make-prog - --without-make-prog - --srcdir=. - --curdir - --ruby=/usr/bin/$(RUBY_BASE_NAME)2.3 - --help - --clean - --use-system-libraries - --enable-static - --disable-static - --with-zlib-dir - --without-zlib-dir - --with-zlib-include - --without-zlib-include=${zlib-dir}/include - --with-zlib-lib - --without-zlib-lib=${zlib-dir}/lib - --enable-cross-build - --disable-cross-build - - To see why this extension failed to compile, please check the mkmf.log which can be found here: - - /home/user/.vagrant.d/gems/extensions/x86_64-linux/2.3.0/nokogiri-1.8.0/mkmf.log - - extconf failed, exit code 1 - - Gem files will remain installed in /home/user/.vagrant.d/gems/gems/nokogiri-1.8.0 for inspection. - Results logged to /home/user/.vagrant.d/gems/extensions/x86_64-linux/2.3.0/nokogiri-1.8.0/gem_make.out - ``` - - In order to solve this make sure that the system has installed packages _lblzma-dev_ and _zliblg-dev_ - - This can be done so by running: - - ``` - sudo apt-get install liblzma-dev zlib1g-dev - ``` diff --git a/_docs/developer/automated_grading.md b/_docs/developer/automated_grading.md deleted file mode 100644 index 43bb3e77..00000000 --- a/_docs/developer/automated_grading.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Automated Grading -category: Developer ---- - -Submitty grades in parallel, under a scheduler daemon running -[`submitty_grading_scheduler.py`](https://github.com/Submitty/Submitty/blob/master/bin/submitty_grading_scheduler.py) -which checks for jobs in the -`/var/local/submitty/to_be_graded_interactive` and -`/var/local/submitty/to_be_graded_batch` queues. - ---- - -In the default system configuration, this script uses 5 parallel -worker processes. To adjust this number: - -1. As root, edit the `/usr/local/submitty/.set/INSTALL_SUBMITTY.sh` - settings and change this line: - - ``` - NUM_GRADING_SCHEDULER_WORKERS=5 - ``` - -2. Then re-install Submitty: - - ``` - sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh - ``` - -Note: If you re-run `CONFIGURE_SUBMITTY.sh` it will undo these changes. - ---- - -To debug new features for autograding, it can be helpful to run -`submitty_grading_scheduler.py` interactively and inspect the output. - -To do this: - -1. Stop the daemon - - ``` - sudo systemctl stop submitty_grading_scheduler - ``` - -2. Now, as the `hwcron` user, run the scheduler and watch the output. - - ``` - sudo su -c '/usr/local/submitty/bin/submitty_grading_scheduler.py' hwcron - ``` - - Use control-C to stop when you've finished your debugging. - -3. Re-Start the daemon - - ``` - sudo systemctl start submitty_grading_scheduler - ``` - - or - - ``` - sudo systemctl restart submitty_grading_scheduler - ``` - - You can check the status of the daemon: - - ``` - systemctl status submitty_grading_scheduler - ``` - -Note: When you re-run `sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh`, -it will stop and restart the autograding scheduler if it is running. (But it will not -start the scheduler, if it is not currently running.) \ No newline at end of file diff --git a/_docs/developer/coding_style_guide.md b/_docs/developer/coding_style_guide.md deleted file mode 100644 index 1970efcf..00000000 --- a/_docs/developer/coding_style_guide.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Coding Style Guide -category: Developer -order: 6 ---- - -To maintain a concise and consistent code base, we'll be trying to adopt a coding style that is loose to allow easy contribution, but also tidy. To do this, we use a combination of style guides per language. Generally, you should be following the style guide for that language closely, though you can potentially deviate within reason. - -The main languages that undergo style critiques on code contributions are C++, Java, PHP, and Python. At some point in the future, for all languages, an appropriate linter (-Xlint for Java, Pylint for Python, etc.) may be added to ensure proper style on contributions. - -### General Notes -Code should mainly be "self-commenting" in that keeping code paths simple (breaking complex interactions into functions) and then commenting the functions as necessary. At a minimum, all functions should have comments that give a short description of function usage, parameter details and return details (giving expected types if it's a dynamic language). - -### PHP -For PHP, please follow the PSR's as laid out by the language developers, except for the cases listed below. Primarily of interest is [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/), though [PSR-4](http://www.php-fig.org/psr/psr-4/) does lay down some useful info about Namespaces in conjunction with autoloading (which is necessary for any new classes added to the system to ensure proper autoloading). Additionally, PHP code should be written such that the [minimum version of PHP that is still supported](http://php.net/supported-versions.php) would work. - -#### if-elseif-else blocks -Each control function should begin on their own line and have one space between the conditional and the opening bracket -```php -core->getQueries()->getUserFromId($user_id); + if ($user) { + return new WebResponse( + "\app\views\user\UserView::class" + 'showUserDetails', + $user + ) + ); + } else { + // render an error + } +} +``` + +From the website, they can now make a request which routes to the +`userDetails` page. Something like +`f20/sample/show_user_details?user_id="aphacker"` + +Because we added `@AccessControl(role="INSTRUCTOR")`, only instructor +level users can access this page. + +The `$user_id` parameter to our function is populated from the +parameters of the GET request `?user_id="aphacker`. + +When we call `$this->core->getQueries()->getUserFromId($user_id);` a +database query is run which loads information for the user with a +matching id into a `UserModel`. See also the [Model](model) documentation. + +## Returning a MultiResponse / WebResponse + +If `$user` was successfully loaded (it's not null), we can render the +page by returning a new MultiResponse object which contains a +WebResponse. + +1. The first parameter of the WebResponse is the path to + `UserView`. In this case it is + `site/app/views/user/UserView`. Submitty automatically preppends + `site/app/views` and adds the word `View` to the end of the last + element in this array. + +2. The second parameter is the name of the function that we want to + call in the `UserView`. In this case `showUserDetails`. + +3. Subsequent parameters are the inputs to the `showUserDetails` + function. + +4. If `$user` didn't load correctly (it is null), we have to return + some error page. This is omitted. + +See more information in the [View](view) documentation. + + +## Disabling a Controller + +There are certain circumstances where a controller should be disabled +completely depending on if a feature is enabled or not within the Config. +To do this, you can utilize the +[`Enabled`](https://github.com/Submitty/Submitty/blob/master/site/app/libraries/routers/Enabled.php) +annotation in the docstring for the controller class, like so: + +```php +use app\libraries\routers\Enabled; + +/** + * @Enabled("forum") + */ +class ForumController {} +``` + +With this annotation in-place, the router will take the string value passed to +the annotation, run [`ucfirst`](https://www.php.net/manual/en/function.ucfirst.php) for it, +and then use that to call the `is{$Feature}Enabled()` function in the Config modal. For the +above example, it would be calling `isForumEnabled()` method. If that method returns false, we +show an access denied error screen to the user, directing them to contact their instructor +if they think it is an error, and then provide a link back to the course home page. diff --git a/_docs/developer/developing_the_php_site/feature_flags.md b/_docs/developer/developing_the_php_site/feature_flags.md new file mode 100644 index 00000000..fd8ab135 --- /dev/null +++ b/_docs/developer/developing_the_php_site/feature_flags.md @@ -0,0 +1,103 @@ +--- +title: Feature Flags +category: Developer +--- + +When developing new features for the site, it may be necessary to have several incremental PRs +to be merged into master. However, within these incremental PRs, it is possible that a release +onto production may happen, containing this in-progress work. While one could put a warning +of "do not use" for the feature, and hope instructors (or students) do not click on it, potentially +breaking the system, it is better to utilize "[Feature Flags](https://en.wikipedia.org/wiki/Feature_toggle)". +The flags can be used to hide a feature, giving access to developers, as well as setting up a +course to alpha or beta test a feature that is not quite ready for full production. + +Feature flags are stored and handled within the Config model, and utilizes the following logic +to determine if a flag is enabled: + +1. If `debugging_enabled` in `config/database.json` is True, then all feature flags are considered on. +1. If `feature_flags` object exists in course `config.json`, then check if requested flag exists in the object +and is set to true (e.g. `flag: true`). + +Otherwise, the flag is considered off. + +E.g: To enable a feature flag in a course named *sample* edit +the file: +```bash +/var/local/submitty/courses/f20/sample/config/config.json +``` + +To include a top level JSON object named feature flags, each feature flag +is a string that can either be true or false. Set a flag to true to enable it for that course. + +Example partial config: + +```json +{ + "feature_flags" : { + "submitty_ocr" : true, + "foo" : false + }, + /* Rest of config below */ + + +``` + + +To utilize checking a flag, the following methods are available: + +1. Twig Template +2. Controller Annotation +3. PHP Code + +## Twig Template + +Within twig, you can use the function `feature_flag_enabled(string $flag): bool`. For example, for +gating on flag foo: + +```twig +{% raw %}{% if feature_flag_enabled('foo') %} + {# show feature foo #} +{% endif %}{% endraw %} +``` + +## Controller Annotation + +To gate a controller, or just a method, you can utilize the `@FeatureFlag` annotation. This annotation +is to be put in the docblock of a controller or method and it accepts a single string argument, the +name of the flag. An example of usage would be: + +```php +use app\libraries\routers\FeatureFlag; +/** + * @FeatureFlag("foo") + */ +class Bar {} +``` + +or for a function: + +```php +use app\libraries\routers\FeatureFlag; + +class Bar { + /** + * @FeatureFlag("foo") + */ + public function bar() {} + + // this function is available always + public function baz() {} +} +``` + +## PHP Code + +For the PHP code, the config model makes available the function +`checkFeatureFlagEnabled(string $flag): bool`. For example, if we wanted to gate on feature flag "foo" within +a controller, we might do: + +```php +if ($this->core->getConfig()->checkFeatureFlagEnabled('foo')) { + // show feature foo +} +``` diff --git a/_docs/developer/developing_the_php_site/index.md b/_docs/developer/developing_the_php_site/index.md new file mode 100644 index 00000000..762fc6ba --- /dev/null +++ b/_docs/developer/developing_the_php_site/index.md @@ -0,0 +1,22 @@ +--- +title: Developing the PHP Site +category: Developer +--- + +The website component of Submitty, where submission, TA grading, +etc. happens is written in PHP following the Model-View-Controller +design pattern. This paradigm allows for organized modular +development, unit testing, and integration of the parts. + + +* [Models](model) hold data, which is often loaded from the +database. For example, a hypothetical `UserModel` would hold +information about a user, like their name or favorite color. + +* [Views](view) render visual information. In this sample example, the +`UserView` would house functions which involve displaying information +about a user. + +* Finally, [Controllers](controller) perform logic. For example, if +you want to load the corresponding `See User Details` page, you might +call the function `userDetailsPage` in the `UserController`. diff --git a/_docs/developer/developing_the_php_site/javascript.md b/_docs/developer/developing_the_php_site/javascript.md new file mode 100644 index 00000000..61879c84 --- /dev/null +++ b/_docs/developer/developing_the_php_site/javascript.md @@ -0,0 +1,64 @@ +--- +title: Frontend JavaScript +--- + +On the frontend, Submitty uses JavaScript to allow for interactivity with the site. Historically, the JS code was written +and imported globally and that lives in the `site/public/js` folder. However, embracing modern standards, we are increasingly +looking to write all new frontend code as ES6 modules. + +[ES6 Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) allow JavaScript code to be split up +into "modules" that can allow other modules to import functions and variables. Modules in Submitty are loaded the +same way as normal JavaScript files using the PHP function `$this->output->addInternalJs(...)`. Unlike normal +JavaScript, modules are "bundled" together by esbuild. This process takes all files imported and creates a single, +minified JavaScript file that is served to the user. + +Unlike regular JS files, ES6 modules are not included into the global JS scope, and are self-contained. When a module is +executed, it only has access to the things that it imports, and we cannot call functions defined within modules directly from +the DOM. As such, to hook a function defined in a module to something in the DOM, such as a click event listener, you will need to +use the addEventListener API. This separation of regular JS and modules also extends to HTML, attributes such as `onclick` +and other inline event handlers cannot call functions defined in modules even if they are exported. + +JavaScript modules are placed in the `Submitty/site/ts` directory and running the install script will launch esbuild +and bundle files, the output will be placed in the `Submitty/site/mjs` directory. You can run the command +`npm run build` to manually bundle files after running `npm install` from the `Submitty/site` directory. + +`npm run build` uses node to run the `Submitty/site/.build.js` file, this contains the logic for searching which files +to transpile and bundle, along with the configuration for esbuild. + +## Creating new modules + +Any new module written should be a `.ts` file to take advantage the type safety of TypeScript. Top levels files +under the `ts` directory are considered entry points and once bundled will create a corresponding `.js` file under +the `public/mjs` directory along with a sourcemap. Support files for your module can be created under a new +directory in the `ts` area, like the `utils` directory. On the PHP side, you will then only need +to include the single corresponding `mjs` file to your top level entry point file. This has the advantage of +reducing the number of files sent to the client. + +## TypeScript + +[TypeScript](https://www.typescriptlang.org/) is a superset of JavaScript that allows strongly typed syntax which is +then transpiled into normal JavaScript. Any file with the `.ts` file type will be transpiled by esbuild as part of the +`npm run build` command and Submitty install script. + + +## Loading JavaScript files + +Once a module or regular JavaScript file is written it needs to be served to the user and included by the HTML. This is +done in PHP through the `addInternalModuleJs` and `addInternalJS`. Each function takes a target filename which is then +sent to the user and timestamped to prevent browsers from caching old versions. These functions are defined in the +`site/app/libraries/Output.php`. + +Both functions work similarly but the `addInternalJS` searches the `site/public/js` directory and `addInternalModuleJs` +searches the `site/public/mjs` directory. + +E.g: + +```php +// searches the site/public/mjs area, its source file would be site/ts/foo.ts +$this->output->addInternalModuleJs('foo.js'); +``` + +```php +// searches the site/public/js area +$this->output->addInternalJS('foo.js'); +``` diff --git a/_docs/developer/developing_the_php_site/model.md b/_docs/developer/developing_the_php_site/model.md new file mode 100644 index 00000000..4e871a67 --- /dev/null +++ b/_docs/developer/developing_the_php_site/model.md @@ -0,0 +1,24 @@ +--- +title: Model +category: Developer +--- + +The Model is part of the [Model-View-Controller](index) software +design pattern. + +The model handles containing the data for the application, performing +data validation, and the rules / logic of the application. It receives +the raw data from the [controller](controller), and then maps that +into a class. A model is then made up of a number of properties, with +getters and setters, and other various functions. + +Each model in Submitty is derived off the `AbstractModel` class which provides +scaffolding for creating getters and setters for class properties. To take advantage +of this, a property must use one of the following annotation tags: + +1. `@prop` (will create both a setter and getter) +1. `@prop-read` (will only create a getter) +1. `@prop-write` (will only create a setter) + +As part of the setter, automatic type-casting will happen based on the type +information passed on the `@var` annotation tag for basic types (string, int, etc.). diff --git a/_docs/developer/developing_the_php_site/view.md b/_docs/developer/developing_the_php_site/view.md new file mode 100644 index 00000000..b1bec369 --- /dev/null +++ b/_docs/developer/developing_the_php_site/view.md @@ -0,0 +1,97 @@ +--- +title: View +category: Developer +--- + +The View is part of the [Model-View-Controller](index) software design +pattern. + +## Example: User View + +The [Controller](controller) will call the view. Let's have a look at +an example `UserView.php`. It might have a function in it like this: + +```php +public function showUserDetails(UserModel $user) { + $this->core->getOutput()->addInternalJs('user-details.js'); + $this->core->getOutput()->addInternalCss('user-details.css'); + return $this->core->getOutput()->renderTwigTemplate( + 'user/UserDetails.twig', + [ + 'user_id' => $user->getUserId(), + 'favorite_color' => $user->getFavoriteColor() + ] + ); +} +``` + +The function `showUserDetails` takes in a `UserModel` object, which +holds all of the data it needs to display. See also the +[Model](model) documentation. + +The first two lines of the function load +`site/public/js/user-details.js` and +`site/public/css/user-details.css`, which contain any page specific +javascript functions or css styling the user details page needs. Some +pages don't require this. + +The third line renders and returns a Twig template found in +`site/app/templates/user/UserDetails.twig`. Twig is the template +language used in Submitty. + +The second parameter of `renderTwigTemplate` is a associative array of +the variables that `UserDetails.twig` needs to properly display. + +## Rendering the User Page with Twig + +Finally, let's look at `UserDetails.twig` + +```html +{% raw %}
+ {{ user_id }}'s favorite color is {{favorite_color}}. +
{% endraw %} +``` + +In this page, we use `user_id` and `favorite_color` to render information +about the student. + +## Another option: Rendering with Vue + +Alternatively, instead of using Twig, we can use [Vue](https://vuejs.org/) instead. + +To do this, first make a Vue page in `site/vue/src/pages` (for example, `site/vue/src/pages/UserDetails.vue`): +```html + + + +``` + + +To actually render this page, we will then need to use the `renderVue` function in our View (ex. `UserView.php`). + +The first paramater of the `renderVue` takes the name of the page (the name of the `.vue` file minus the extension, in this case `UserDetails`), and the second parameter is the same as in `renderTwig`, an associative array of variables that are passed to the Vue page. + +If we wanted our `UserView.php` example to render with Vue, it would have a function that might look like this: + +```php +public function showUserDetails(UserModel $user) { + return $this->core->getOutput()->renderVue( + 'UserDetails', + [ + 'user_id' => $user->getUserId(), + 'favorite_color' => $user->getFavoriteColor() + ] + ); +} +``` + +To access the variables passed by the `renderVue` function in Vue, use [`inject`](https://vuejs.org/api/composition-api-dependency-injection.html#inject). The injection keys will be the same as the keys in the provided array. If the key provided to `inject` is not in the array passed to `renderVue`, it will return `undefined`. \ No newline at end of file diff --git a/_docs/developer/developing_the_php_site/websocket.md b/_docs/developer/developing_the_php_site/websocket.md new file mode 100644 index 00000000..bb9c0217 --- /dev/null +++ b/_docs/developer/developing_the_php_site/websocket.md @@ -0,0 +1,109 @@ +--- +title: WebSocket +--- + +The PHP site for Submitty is mostly used through regular HTTP calls which return a rendered HTML page +for the user to interact with in a static fashion. Updating content happens through a page refresh for +the user. While this works well in a lot of instances, it does not work well in environments were we +expect a lot of people simultaneously editing or interacting with a particular page. For example, on +the simple grading interface, we might expect multiple graders to be simultaneously entering information +for students during an in-person lab. We want the page to be automatically updating as new information is +inputted by the graders. To handle this sort of use-case, we rely on +[WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API). These WebSockets allow +a page to connect to the server on the user's open page, and it will receive data as it is incoming. + +While WebSockets can only transmit strings, there is an expectation that JSON is used as the transport +encoding, and that anything sent can be safely run through `JSON.decode` / `json_decode`. + +Submitty surfaces its WebSocket server on the localhost using `ws://localhost:41983` and then through +apache / externally through `ws:///ws` (e.g. `ws://localhost:1511/ws` on Vagrant). + +__Note__: Ideally, a page should still be usable without WebSockets being available / active, to ensure +accessibility to all users. + +## Setting up WebSockets + +To utilize the WebSockets, there are two parts to this, the PHP code and the client-side JS code. The JS +code is responsible for receiving new data from the WebSocket and updating the rendering of the page +as appropriate, as well as receiving an update from a single user. The PHP code is responsible for handling +incoming input, and appropriately broadcasting it to all users. + +## PHP Side + +For communicating with the WebSocket server, you can utilize this snippet: + +```php +use WebSocket; +try { + $client = new Websocket\Client("ws://localhost:41983"); + $client->send('string data'); + $client->close(); +} +catch(WebSocket\ConnectionException $e) { + // handle exception +} +``` + +which will send the message to the central Server. To the modify how it a message get handles, you will want to modify +the [`\app\libraries\socket\Server`](https://github.com/Submitty/Submitty/blob/master/site/app/libraries/socket/Server.php#L175)`::onMessage` +function. + +Finally, to allow a client page to use websockets, you should include the `site/public/js/websocket.js` file within your +view by using: + +```php +$this->output->addInternalJs('websocket.js'); +``` + +See below for more details on then how to utilize this file. + +## JS Side + +On the client-side, you can set-up a page to utilize the WebSocket by doing: + +```js +const client = WebSocketClient(); +client.onmessage = (msg) => { + // do something with msg +} +client.onopen = () => { + // do something on opening connection +}; + +client.open(); +``` + +The `WebSocketClient` is an extension of the plain `WebSocket` implementation +which features automatic reconnection of a socket, as well as running `JSON.stringify` and +`JSON.parse` over incoming and outgoing messages. If you so desire, you could utilize +a `WebSocket`. + +### Ensure WebSocket Server is running + +To help validate that the WebSocket server is up and running, you can send a basic `ping` +message and get back a `pong` message. For example, using JavaScript: + +```js +const ws = new WebSocket('ws://localhost:1511/ws'); +ws.onmessage = (data) => console.log(data); +ws.send('ping'); +``` + +### Debugging WebSocket in HTTPS + +Note that most browsers do not trust WebSocket traffics with self- +signed certificates. If you are dealing with WebSocket related features, +there are some workarounds: + +- Copy the certificates from your VM and trust it on your host system; + +- OR, Trust/Ignore the certificates on your browser; + +- OR, Downgrade to HTTP/1.1 without TLS using `bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/dev-upgrade-h2.sh down`. + +You could try following to trust/ignore certificates on your browser: + +- For Chrome, start Chrome with `--ignore-certificate-errors`. + +- For Firefox, trust the certificate when the warning pops up; + And go to `https://localhost:8443/ws` and hit trust again. diff --git a/_docs/developer/development_instructions.md b/_docs/developer/development_instructions.md deleted file mode 100644 index 6d1a9fec..00000000 --- a/_docs/developer/development_instructions.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Development Instructions -category: Developer -order: 3 ---- - -We recommend that you do all file edits within your checkout of the -Submitty GIT repository. This is a shared directory between the host -machine and the virtual machine, so you can use your favorite -code/text editor on your local machine. - -The different stages of the installation and build process copy files -from the repository to the installation directories, substitute -variables, compile libraries, and change permissions. Depending on -the type of change, you will need to do different levels of -re-installation to test those changes. The instructions below apply -to changes you have made within your local Submitty checkout -(including pulling new code from GitHub or switching to another -branch). - ---- - -* If you've made changes to files affecting the system installation - process (changes to `CONFIGURE_SUBMITTY.sh`, `install_system.sh`, - `Vagrantfile`), you should re-create your VM from scratch to ensure - the changes are correct. Exit the VM, and from a terminal your - host machine within the Submitty GIT repository type: - - ``` - vagrant destroy - vagrant up - ``` - - _NOTE: This process will take a bit of time (~30 minutes), and - requires an internet connection. It will delete any assignments - you've uploaded to your VM installation. And it will erase any - files you have created/edited within your VM that are not part of - the shared directory of the Submitty working repository. It will - also destroy the databases, and any grading configuration or grading - work that has been done._ - - -* Depending on the configuration/setup changes that you're developing, - you may be able to more quickly test those changes by - re-provisioning the existing VM. Exit the VM, and from a terminal - on your host machine within the Submitty GIT repository type: - - ``` - vagrant reload --provision - ``` - - If the vagrant box is not running, you would run the command: - - ``` - vagrant up --provision - ``` - ---- - - -* If you've changed the script to create a new course - (`create_course.sh`), or the schema for the course database - (`tables.sql`), we need to delete all courses, and recreate the - course databases, users, and sample submission uploads. - - _NOTE: To avoid accidental use on the live server, the partial - reset script first checks for the existence of a .vagrant folder._ - - _NOTE: You will need to not be connected to any DBs (such as through - pgAdmin) or else running the below scripts could put things into a - broken state._ - - Run these commands: - - ``` - cd /usr/local/submitty/GIT_CHECKOUT_Submitty/ - sudo /usr/local/submitty/GIT_CHECKOUT_Submitty/.setup/bin/partial_reset.py - sudo /usr/local/submitty/GIT_CHECKOUT_Submitty/.setup/bin/setup_sample_courses.py - sudo service php7.0-fpm restart - echo 'partial reset complete' - ``` - - - If there are changes to the auxiliary Tutorial or AnalysisTools - repos, you may also need to pull those changes: - - ``` - sudo /usr/local/submitty/.setup/bin/update_repos.py - ``` - ---- - -* If you've changed `INSTALL_SUBMITTY_HELPER.sh`, or if you've changed - any php/website files, re-install: - - ``` - sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh - ``` - - _NOTE: This command uses rsync and should run reasonably fast since - it's only copying and rebuilding what has changed._ - - If you've moved/deleted files, it's good to do a fresh install of - the Submitty code: - - ``` - sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh clean - ``` - ---- - -* If you've changed the C++ code for the testing and autograding - library, you must re-install the grading code (which rebuilds the - grading library). - - Or, if you've added or changed any of the sample provided - assignments within the Submitty repository, they need to be copied - from the repository to the installation location. - - In either case, run: - - ``` - sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh clean - ``` - - _NOTE: The `clean` argument is usually not necessary, and - installation runs faster without it._ - - You will also need to re-run the `BUILD_coursename.sh` script for - any courses that you're using for testing, e.g.: - - ``` - /var/local/submitty/courses/s17/course_01/BUILD_course_01.sh - ``` - - Or re-run the BUILD script for all courses: - - ``` - for s in /var/local/submitty/courses/*/*; do c=`basename $s`; ${s}/BUILD_${c}.sh; done - ``` - - And see also [Batch Regrade Homeworks](../instructor/batch_regrade_submissions) - - For convenience, here are the commands to copy-paste to install, - build all courses, and regrade everything. - - ``` - sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh clean && \ - for s in /var/local/submitty/courses/*/*; do c=`basename $s`; ${s}/BUILD_${c}.sh; done && \ - echo 'y' | /usr/local/submitty/bin/regrade.py /var/local/submitty/courses/ && \ - /usr/local/submitty/bin/grading_done.py - ``` - ---- - -* If you've changed a homework configuration that is not from the - Submitty respository sample assignments, just rebuild the course - that uses that homework: - - ``` - /var/local/submitty/courses/s17/course_01/BUILD_course_01.sh - ``` - - And see also [Batch Regrade Homeworks](../instructor/batch_regrade_submissions) - ---- - -* If the VM has a clock skew (incorrect time) - - ``` - sudo service ntp stop - sudo ntpd -gq - sudo service ntp start - ``` - ---- - -* If the JavaScript files have changed and there are errors or you do not see the changes then you may need to clear your browser's cache - - - For Chrome: Choose the menu button, then "More tools", then "Clear browsing data" - - For Firefox: Choose the menu button, then "Options", then "Advanced" in the "Network" tab under "Cached Web Content" click "Clear Now" - - For Edge: Choose the Hub icon then the History icon, then "Clear all history" diff --git a/_docs/developer/development_instructions/automated_grading.md b/_docs/developer/development_instructions/automated_grading.md new file mode 100644 index 00000000..ecd0ef34 --- /dev/null +++ b/_docs/developer/development_instructions/automated_grading.md @@ -0,0 +1,220 @@ +--- +title: Automated Grading +category: Developer > Development Instructions > Advanced Development +redirect_from: + - /developer/automated_grading +--- + +Starting with Submitty version `v.1.1.0`, automated grading is +controlled by two daemons, +[`submitty_autograding_shipper.py`](https://github.com/Submitty/Submitty/blob/master/autograder/submitty_autograding_shipper.py) +and +[`submitty_autograding_worker.py`](https://github.com/Submitty/Submitty/blob/master/autograder/submitty_autograding_worker.py). + +_NOTE: Versions of Submitty prior to `v.1.1.0` use a +submitty_grading_scheduler -- see instructions at the bottom of this page._ + +In the simple use case, with a single server, both daemons run on the +same machine. In more complex use cases Submitty can be configured to +ship jobs from the *primary* machine to one or more *worker* machines. +This can be useful to manage very large numbers of submissions near +deadlines, or to facilitate use of specific hardware or extra +resources for certain assignments. + +Automated grading of multiple homeworks can be done in parallel. The +system administrator should adjust the Submitty configurations +described below to match the hardware specifications and the typical +homework submission for your courses. + +The shipper manager/daemon on the primary machine runs a *shipper +process* for each *worker process* running on the primary machine or +worker machine. + +--- + +## Default Configuration -- Single Server + +In the default system configuration, the shipper manager will launch 5 +shipper processes on the primary machine and the worker manager will +launch 5 worker processes on the primary machine. To adjust this +number: + +1. As root, edit the `/usr/local/submitty/config/autograding_workers.json` + settings and edit the `num_autograding_workers` field as desired: + + ``` + "primary": { + "address": "localhost", + "num_autograding_workers": 5, + "username": "", + "capabilities": [ + "default" + ] + } + ``` + +2. Then re-install Submitty: + + ``` + sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh + ``` + + _NOTE: If you delete the `autograding_workers.json` file and re-run + `CONFIGURE_SUBMITTY.py`, the file will be re-created with the + default settings._ + +--- + +## Multiple Physical Servers + +1. To specify additional physical machines as worker machines, add one or more + additional object(s) to the `autograding_workers.json` file, one for each additional machine. For example: + + ``` + "foobarbaz" : { + "address" : "foobarbaz.example.com", + "username": "submitty", + "capabilities": [ + "extra_ram" + ], + "enabled": true, + "num_autograding_workers": 2 + } + ``` + + Make sure to insert the correct username and ip address for each + worker machine. Also specify the number of simultaneous workers on + each worker machine, and the capabilities of each machine. At + least one machine in the pool must specify the capability + `"default"`. The capabilities can be any string, and customized to + your courses and hardware. + + _NOTE: You may specify that no autograding should be done on the primary machine + and instead ship all autograding tasks to the worker machines by specifying + `num_autograding_workers` to be zero for the `"primary"` machine._ + + +2. Setting up the worker machine(s): + + Follow the [worker installation instructions](/sysadmin/installation/worker_installation) + + +3. Next, create homework assignment autograding configurations that + specify jobs that should be shipped. In your `config.json` file, + add the `"required_capabilities"` field: + + ``` + "required_capabilities" : "extra_ram" + ``` + + If you don't include this field, it will be set to `"default"`. + Each shipper process launched by the shipper manager is assigned to + a worker machine and regularly scans the autograding tasks, + searching for a submission with required capabilities that matches + the capabilities of its worker machine. + + _TODO: Discuss more, including machines and/or gradeable + configs having multiple values for this field._ + +--- + +## Debugging + +To debug new features for autograding, it can be helpful to run +`submitty_autograding_shipper.py` and `submitty_autograding_worker.py` +interactively and inspect the output. + +_NOTE: A cron job runs hourly to detect autograding shipper outages on the primary machine. To avoid interference during debugging, this job should be disabled before proceeding. See [Capture Cron Error Messages](/sysadmin/installation/system_customization#capture-cron-error-messages) for instructions on disabling the script._ + +To do this: + +1. Stop the daemons (on each server, as appropriate) + + ``` + sudo systemctl stop submitty_autograding_shipper + 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. + + ``` + sudo su -c '/usr/local/submitty/autograder/submitty_autograding_shipper.py' submitty_daemon + ``` + + And similarly from each machine that will be autograding (including + the primary machine, as appropriate), run the worker manager and + watch the output: + + ``` + sudo su -c '/usr/local/submitty/autograder/submitty_autograding_worker.py' submitty_daemon + ``` + + +3. Use control-C to stop the shipper and worker managers when you've + finished your debugging. + + +4. Re-Start the daemons + + ``` + sudo systemctl start submitty_autograding_shipper + sudo systemctl start submitty_autograding_worker + ``` + + or + + ``` + sudo systemctl restart submitty_autograding_shipper + sudo systemctl restart submitty_autograding_worker + ``` + + You can check the status of the daemons: + + ``` + sudo systemctl status submitty_autograding_shipper + sudo systemctl status submitty_autograding_worker + ``` + +_NOTE: When you re-run `sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh`, it will stop and +restart the autograding shipper and worker if it is running. (But it +will not start the scheduler, if it is not currently running.)_ + +_TODO: We will want to allow control of installation/upgrade of new +code & system configurations on the worker machines from the primary +machines. Currently installation/upgrade on the worker machines must +be done manually._ + + +--- + +## Restart all Shippers and Workers on Primary and Remote Machines + +The following script will stop and restart all of the shippers & +workers on the primary and worker machines, in the right order. + +``` +sudo python3 /usr/local/submitty/sbin/restart_shipper_and_all_workers.py +``` + +If one of the remote machines is not reachable, its use will be +disabled on the primary machine. Once it is rebooted or the network +is repaired it must be manually re-enabled by editing the appropriate +field in this configuration file: + +``` +/usr/local/submitty/config/autograding_workers.json +``` + +Then the script above can be re-run to start remote grading on that +machine. diff --git a/_docs/developer/configuring_tie_in_programs.md b/_docs/developer/development_instructions/configuring_tie_in_programs.md similarity index 94% rename from _docs/developer/configuring_tie_in_programs.md rename to _docs/developer/development_instructions/configuring_tie_in_programs.md index cf5ecc4e..0525a7d1 100644 --- a/_docs/developer/configuring_tie_in_programs.md +++ b/_docs/developer/development_instructions/configuring_tie_in_programs.md @@ -1,7 +1,8 @@ --- title: Configuring Tie In Programs -category: Developer -order: 12 +category: Developer > Development Instructions > Advanced Development +redirect_from: + - /developer/configuring_tie_in_programs --- It is possible to configure Submitty to use various third party programs to run student code. This page details any special configuration steps necessary to set up such programs. @@ -32,7 +33,7 @@ _**NOTE:**_ make sure that your computer login name matches the name of the user 11. Copy your file installation key. You will need it in the next step. ##### Semi-Automated Install -1. Navigate to /usr/local/submitty/GIT_CHECKOUT/.setup/bin/ +1. Navigate to /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/bin/ 2. Open MatlabInstall.sh with your favorite text editor. 3. Set the ABSOLUTE_PATH_TO_INSTALLATION_FILES variable to which you moved the files in step 3 above. 4. Set the INSTALLATION_KEY variable to be equal to the key you copied in step 11 above. diff --git a/_docs/developer/development_instructions/index.md b/_docs/developer/development_instructions/index.md new file mode 100644 index 00000000..0b2d9390 --- /dev/null +++ b/_docs/developer/development_instructions/index.md @@ -0,0 +1,323 @@ +--- +title: Overview +category: Developer > Development Instructions +redirect_from: + - /developer/development_instructions + - /developer/development_instructions/index +--- + +We recommend that you do all file edits within your checkout of the +Submitty GIT repository on your local / host machine. This is a +shared directory between the host machine and the virtual machine, so +you can use your favorite code/text editor on your local machine. + +The different stages of the installation and build process copy files +from the repository to the installation directories, substitute +variables, compile libraries, and change permissions. Depending on +the type of software change, you will need to do different levels of +re-installation to test those changes. The instructions below apply +to changes you have made within your local Submitty checkout +(including pulling new code from GitHub or switching to another +branch). + +_NOTE: Depending on the types of changes you have made, the complexity of the +reinstallation will vary (and thus also the time necessary to complete +the installation). This page is organized with the simplest and least +expensive reinstallation steps at the top of the page, and the more +complicated and expensive steps at the bottom of the page._ + +Please also see [Installation Version Notes](/sysadmin/installation/version_notes) + +--- + +## Submitty Help - List of Shortcuts + +* All of the commands below should be typed into the Vagrant VM + terminal. That is, after you have completed the + [vagrant setup instructions](/developer/vm_install_using_vagrant) + and typed: + + ``` + vagrant ssh + ``` + + +* To see the available command shortcuts/aliases, from the Vagrant VM + terminal you can type: + + ``` + submitty_help + ``` + +--- + +## 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), 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 + ``` + + Which is equivalent to running this full command: + + ``` + sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY_HELPER_SITE.sh + ``` + +* Similarly, other minor or modest changes to the `bin` and/or `sbin` + directories can be applied with this shortcut: + + ``` + submitty_install_bin + ``` + + Which is equivalent to running this full command: + + ``` + sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY_HELPER_BIN.sh + ``` + +--- + +## Incremental Development Updates + +When _incrementally_ editing code in the `site`, `bin`, or `sbin` +directories, you can enable the Submitty development *code watcher* to +automatically detect and automatically update those files on your +installation through the scripts described above. The code watcher is +convenient for testing changes to the website appearance (e.g., simple +edits to CSS or twig/html/php). Once the update finishes, you should +be able to reload the website and see the update. + +* To enable the code watcher, run this shortcut from the vagrant terminal: + + ``` + submitty_code_watcher + ``` + + Which is equivalent to running this full command: + + ``` + sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/bin/code_watcher.py + ``` + + Or instead, you may run this command from your host computer: + + ``` + vagrant ssh -c "python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/bin/code_watcher.py" + ``` + + Leave this terminal open after starting the code watcher. Each time + you save a file, text output from the installation process will + scroll in this terminal. Press Control C in this terminal to + disable / stop the code watcher. + + +* Alternately, many of our developers like the efficiency of the + PhpStorm IDE (integrated development environment) for incremental + editing and development of website files. + + See also: [PhpStorm configuration instructions](/developer/getting_started/phpstorm) + + +### Clearing Your Browser Cache + + +* If the JavaScript files have changed and there are errors or you do not see the + changes then you may need to clear your browser's cache. + + **For Chrome:** Choose the menu button, then "More tools", then "Clear browsing data" + + **For Firefox:** Choose the menu button, then "Options", then "Advanced" in the + "Network" tab under "Cached Web Content" click "Clear Now" + + **For Microsoft Edge:** Choose the Hub icon then the History icon, then "Clear all history" + +* If the Twig files which are being cached by the browser or/and there + are errors then you may again need to clear your browser's cache + or/and cookies. [To make sure your actions don't affect other site, + you can clear cache from the past hour]. + + + +--- + +## Update _ALL_ Submitty Software + +If you have made changes to the autograding pipeline or other more +significant changes to Submitty infrastructure, it may be necessary to +re-compile source code, apply database changes, update third-party +libraries, and restart daemon processes. + +Similarly, if you are upgrading your current working branch with +multiple pull requests from the `main` Submitty branch, or if you are +reviewing and testing the pull request from another developer that may +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: + + ``` + submitty_install + ``` + + Which is equivalent to running this full command: + + ``` + sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh + ``` + + _NOTE: This command uses rsync and should run reasonably fast (1-2 + minutes) since it's only copying and rebuilding what has changed._ + + +* If recent changes have moved/renamed/deleted files, it's good to do + a `clean` install of the Submitty source code, which deletes and + then re-copies these source code directories: + + ``` + sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh clean + ``` + + +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: + +* [Rebuild Gradeables](/instructor/assignment_preparation/index#builddebug-all-grading-configurations) using those configurations, and also + +* [Batch Regrade Homeworks](/instructor/batch_regrade_submissions) already submitted to those gradeables. + + +--- + +## System Re-Configuration + +If recent development changes include modifications to files affecting +the system installation process (e.g., changes to +`CONFIGURE_SUBMITTY.py`, `install_system.sh`, `Vagrantfile`), you will +need to either re-provision or re-build your VM from scratch to test +these changes. + +* To re-run the initial configuration step of Submitty, use this command: + + ``` + sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/CONFIGURE_SUBMITTY.py + ``` + +* To update existing databases: + + ``` + sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/update_database.py + ``` + +--- + +## Re-Creating All Sample Course Data +* 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`), 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 + pgAdmin) or else running the below scripts could put things into a + broken state._ + + Run this command: + + ``` + sudo bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/bin/recreate_sample_courses.sh + ``` + + You can append the `--no_submissions` flag to the above command to + skip creation of any sample submission data in the sample courses. + This will accelerate the completion of this command, but you will be + missing the hundreds of sample student submissions present in the + full installation. + + You can append the `--test_only_grading` flag to the above command to + more closely mimic the version that is on the Cypress CI. + + If you only need a certain courses, you can append each course name to + the above command to only create the courses you want. + + _NOTE: If you mistype a course, that course will not be created. If you + only have mistyped courses, then no courses gets created._ + + + 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 + +* To re-provision your VM, exit the VM, and from a terminal your host + machine within the Submitty GIT repository type: + + ``` + vagrant reload --provision + ``` + + Or if the VM is not already running: + + ``` + vagrant up --provision + ``` + + This is will be faster than doing a full `destroy`/`up`, however + depending on the changes you've done to the VM, could leave it + potentially unstable. + +* Alternatively, re-build your VM from scratch: + + ``` + vagrant destroy + vagrant up + ``` + + _NOTE: This process will take a bit of time (45 minutes or more), + and requires an internet connection. It will delete any assignments + you've uploaded to your VM installation. And it will erase any + files you have created/edited within your VM that are not part of + the shared directory of the Submitty working repository. It will + 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. + diff --git a/_docs/developer/development_instructions/jobs_daemon.md b/_docs/developer/development_instructions/jobs_daemon.md new file mode 100644 index 00000000..27debc66 --- /dev/null +++ b/_docs/developer/development_instructions/jobs_daemon.md @@ -0,0 +1,68 @@ +--- +title: Jobs Daemon & Debugging +category: Developer > Development Instructions > Advanced Development +redirect_from: + - /developer/jobs_daemon +--- + + +Submitty has a daemon to run various helper jobs. The system is +configured by default to run at most five jobs in parallel. When an +instructor creates or edits a gradeable, the build script for the +autograding configuration is automatically placed into this job queue. +Similarly, when a new plagiarism detection task is created or an +existing one is edited, a job is placed in the queue. + + + +* The details for each job are written to a .json file in the + `/var/local/submitty/daemon_job_queue/` directory. + + +* Check the status of the daemon: + + ``` + sudo systemctl status submitty_daemon_jobs_handler + ``` + + +* If necessary, try to restart the jobs daemon: + + ``` + sudo systemctl restart submitty_daemon_jobs_handler + ``` + + +* Look at the more detailed, recent stdout & stderr from the websocket daemon: + + ``` + sudo journalctl -u submitty_daemon_jobs_handler + ``` + + +* When debugging, it can be helpful to manually run the daemon and + inspect the output: + + First, stop the daemon: + + ``` + sudo systemctl stop submitty_daemon_jobs_handler + ``` + + Then run the daemon directly: + + ``` + sudo su -c '/usr/local/submitty/sbin/submitty_daemon_jobs/submitty_daemon_jobs.py' submitty_daemon + ``` + + When you are done, start the daemon again: + + ``` + sudo systemctl start submitty_daemon_jobs_handler + ``` + + + + +_NOTE: When you re-run `sudo /usr/local/submitty/.setup/INSTALL_SUBMITTY.sh`, it will stop and +restart the jobs daemon if it is running._ diff --git a/_docs/developer/development_instructions/localization.md b/_docs/developer/development_instructions/localization.md new file mode 100644 index 00000000..0c77e7e5 --- /dev/null +++ b/_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: + +``` +

Text in the page I will translate

+``` + + +And replace that text string with the following syntax: + +``` +

{ { localize("Page_Description.Text_To_Translate", "Text in the page I will translate") } }

+``` + +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: +``` +_.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. + diff --git a/_docs/developer/development_instructions/merge_conflicts.md b/_docs/developer/development_instructions/merge_conflicts.md new file mode 100644 index 00000000..51945bf3 --- /dev/null +++ b/_docs/developer/development_instructions/merge_conflicts.md @@ -0,0 +1,65 @@ +--- +title: Resolving Merge Conflicts +category: Developer +--- + +Most of the time, `git` will easily and correctly combine the +simultaneous work of two or more developers. However, if two +developers have both edited the same lines or nearby lines of a single +file, `git` will err on the side of caution and require that a +developer who is familiar with the specific file and the recent +changes to manually resolve this *merge conflict*. + +For simple merge conflicts, it is often possible to resolve the merge +conflict using the GitHub web GUI for file editing. But sometimes, it +is necessary to use the git command line and an editor on your local +machine. + + + +## Composer PHP Package Manager Files + +As a specific example, let's resolve a merge conflict with the +`composer.lock` file: + +1. Make sure master is up-to-date: + + ``` + git checkout master + git pull + ``` + +2. Checkout your branch: + + ``` + git checkout + ``` + +3. Replace the `composer.json` and `composer.lock` file in this branch with that of master: + + ``` + git checkout master -- site/composer.lock site/composer.json + ``` + +4. Commit changed files: + + ``` + git add . + git commit -m "wip" + ``` + +5. Merge master: + + ``` + git merge master + ``` + +6. Then re-introduce your dependency: + + ``` + pushd site + composer require + popd + ``` + +7. Commit the updated `composer.json` and `composer.lock` files. \ No newline at end of file diff --git a/_docs/developer/development_instructions/migrations.md b/_docs/developer/development_instructions/migrations.md new file mode 100644 index 00000000..8a8bde52 --- /dev/null +++ b/_docs/developer/development_instructions/migrations.md @@ -0,0 +1,197 @@ +--- +title: Migrations +category: Developer > Development Instructions +redirect_from: + - /developer/migrations +--- + +We use [database migrations](https://en.wikipedia.org/wiki/Schema_migration) +to handle updating Submitty's databases, both in development and production, +in such a way that it is repeatable, easy to see the status of a given database, +and that we are not left with partial DB upgrades due to a broken script. + +To do this, we utilize a custom migration tool written for Submitty, +[migrator](https://github.com/Submitty/Submitty/tree/master/migration). This tool +can be used manually, as well as being baked into the +installation/upgrade procedure of Submitty. For instance, running +`/usr/local/submitty/.setup/INSTALL_SUBMITTY.sh` will apply any pending +migrations for all environments. + +The migrator tool has three distinct "environments" that all have their +own unique list of migrations. They are: +* system +* master +* course + +Where `system` migrations should deal mainly with package installation/changes, +system changes, new dependencies, etc. `master` migrations deal with changes to the master Submitty +database. `course` migrations are applied individually to each course +detected in `/var/local/submitty/courses` and can be used to adjust the +courses' DB, config files, etc. + +For all commands, it is required that you pass in the environment you wish +to operate on to migrator. + +See also: [System Administration / Update Submitty](/sysadmin/installation/update_submitty) + +NOTE: Some mandatory installation updates _should not be implemented_ +via the migration system if automatic updates may be problematic due +to customized installation. For example, Submitty updates should not +attempt to automatically edit the Apache configuration. PR's requiring +manual system administrator edits before/after installation should be +prefixed by `[SYSADMIN ACTION]`. + +See also: [How to make a Pull Request(PR) to Submitty](/developer/getting_started/make_a_pull_request) + + +### Manually Applying Migrations + +To manually run or apply all new, unapplied migrations to your system +and existing courses you can run: + +``` +sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e migrate +``` + +Migrations are run in chronological order in a set order of `master`, +`system`, and then `course`, regardless the order you specify the environments +on the CLI. + +After a migration is applied, the status is stored in the master +database (for system or master database migrations) or the course +database (for course migrations). + +To see additional options, run: + +``` +sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -h +``` + + +### Rolling Back or Reverting a Migration + +It can be useful during development to rollback or undo a migration. +The commands below will undo the most recent migration (in +chronological order) to the system installation, master database, or +course database, respectively: + +``` +sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e system rollback +``` + +``` +sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e master rollback +``` + +``` +sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e course rollback +``` + +### View Status of Migrations + +It may be useful to get an overview of the status of migrations for the +different environments. To do this, run: + +``` +sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e status +``` + +This will output a table showing the migrations that are `UP` or `DOWN`. + +### Writing New Migrations + +If your bugfix or new feature requires a change to the system +installation, or the master or course database, or the course +directory or file structure: + + +1. You should make the necessary edits to build a new system from + scratch in the relevant files, e.g.: + + `GIT_CHECKOUT/Submitty/.setup/install_system.sh`, or the files in + `GIT_CHECKOUT/Submitty/.setup/distro_setup/` + + +2. And you should also prepare a migration file of the appropriate + type (`system`, `master`, or `course`) to update an existing system and + existing courses. A migration is a python file with 2 optional functions, + `up` (called for the `migrate` command) and `down` (called for the + `rollback` command). Run the appropriate command below to create + the template with the appropriate function signatures: + + ``` + sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e system create + ``` + + ``` + sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e master create + ``` + + ``` + sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e course create + ``` + + A new file will be created in the + appropriate subfolder of + `/usr/local/submitty/GIT_CHECKOUT/Submitty/migration/migrator/migrations/`. + The file will be named with the current date (year, month, day, + hour, minute, second) and migration name string you supplied. + The filename pattern will allow the migration system to + chronologically sort your changes relative to existing & future + changes. The created file has a string defining the arguments + for that file, but largely, it's a config object for Submitty + (for accessing info stored in `/usr/local/submitty/config`), a + database object to make changes to the DB via a SQLAlchemy + session, and then for course migration, the semester and course + being affected. For interacting with the DB, you'll mainly just + want to use: + + ``` + database.execute("SQL QUERY TO RUN") + ``` + + which will run the query automatically within a transaction that's + started before running the migration file. + + See the [existing migrations](https://github.com/Submitty/Submitty/tree/master/migration/migrator/migrations) + for examples. + + NOTE: The `up` and `down` functions are optional to be defined and + you can omit the function if you do not need it for your migration. + + NOTE: In general, your `down` migration should only undo the + necessary changes to make earlier versions of the Submitty + software work. For example, if your migration is adding a column + to an existing table in the database, it is probably not necessary + or desirable to delete that data in the `down` function. We don't + want to lose any data since we likely plan to return to this state + in the future. Your `down` function may be empty. + + Thus, it is important to ensure that the `up` migration can be + re-run after the corresponding `down` migration is run. For example, + your `up` function should not crash on adding the column if the column + already exists. + + +3. After you have written your migration to update an existing system + and are satisfied with it, you must also update the base .sql + files used to create a new Submitty system. To + accomplish this, first apply the migration that you wrote in the previous + step, placing the DB into the desired end state, and then run the following + command from within the Vagrant VM: + + ```bash + sudo python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/migration/run_migrator.py -e master -e course dump + ``` + + This will update `migration/migrator/data/submitty_db.sql` and `migration/migrator/data/course_tables.sql`. + If you only wish to update one of them, you can use just `-e master` for `submitty_db.sql` and `-e course` + and `course_tables.sql`. + + +4. Lastly, you should verify that the edits made to the database schema(s) match what you intended to edit in the following file(s): + + `GIT_CHECKOUT/Submitty/migration/migrator/data/submitty_db.sql` + `GIT_CHECKOUT/Submitty/migration/migrator/data/course_tables.sql` + + If the edits are not inline with what you intended, you may have to modify your new migration in order to achieve the desired result. diff --git a/_docs/developer/development_instructions/miscellaneous.md b/_docs/developer/development_instructions/miscellaneous.md new file mode 100644 index 00000000..83197f84 --- /dev/null +++ b/_docs/developer/development_instructions/miscellaneous.md @@ -0,0 +1,46 @@ +--- +title: Miscellaneous +category: Developer > Development Instructions +--- + + +## Testing Authentication + +Our vagrant environment defaults to PAM authentication, but is also +setup to easily use any of the other supported authentication methods. + +To switch, either re-run CONFIGURE_SUBMITTY.py or edit +`/usr/local/submitty/config/authentication.json` and change the +authentication method to any of the methods. You should be able +to leave all other settings to the default. + +#### LDAP + +For `LdapAuthentication`, the default settings are: + +```json +"ldap_options": { + "url": "ldap://localhost", + "uid": "uid", + "bind_dn": "ou=users,dc=vagrant,dc=local" +} +``` + +When using DatabaseAuthentication, Submitty allows users to +[change their password](/student/account/password) from the home screen. + + +#### SAML + +To easily setup SAML authentication locally: You can run the following +command which will switch to SAML, generate the necessary keys, turn +on the required Docker container, and add all users to the mapping table. + +``` +bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/testing/setup_saml.sh +``` + +This SAML IdP hooks into the LDAP system on the vagrant machine. So if you +cannot log in, try testing LDAP first as that could be a reason it fails. + + diff --git a/_docs/developer/development_instructions/performance_testing.md b/_docs/developer/development_instructions/performance_testing.md new file mode 100644 index 00000000..740b7141 --- /dev/null +++ b/_docs/developer/development_instructions/performance_testing.md @@ -0,0 +1,54 @@ +--- +title: Performance Testing +category: Developer > Development Instructions > Advanced Development +--- + + +There are a couple ways of measuring performance of the Submitty webserver. +Below lists a few ways it can be done. + +## Xdebug + +This is useful for determining what function calls take the longest in a single +page load. If you notice a specific page take significantly long, you can enable +the Xdebug profiler to create a profile output to see what PHP functions take +the longest. See more info about setting this up +[here](/developer/getting_started/xdebug). + +## Apache Bench + +Apache Bench is useful for testing to see how many requests a server can handle +and see how fast it handles those requests. You can specify how many requests and +how much concurrency to send those requests at. This can allow you to change +a couple settings/code and see the difference that it makes on the server. + +Here is an example of how you can run Apache Bench locally: +`ab -n 1000 -c 50 http://localhost:1511/`. This performs 1000 requests with 50 +concurrent requests. + +If you want to add the submitty session cookie to avoid unauthorized requests you +can do the following: `ab -n 1000 -c 50 -C "submitty_session=XXX" http://localhost:1511/`. +You can copy your submitty_session from your cookies on your browser. + +If you want to test this on a production server then just replace `http://localhost:1511/` +with your URL. + +_NOTE: Only run this on a server that you have permission to do so on._ + +## SQL + +#### Viewing Queries Executed by Submitty + +When Submitty is in debug mode (enabled by default in a Vagrant VM), the footer of pages will have an additional `Show Page Details` link which shows all queries that were made on the database in the process of rendering the page. +#### Running Queries + +See the [Database Design page](/developer/software_and_system_design/database_design) for information about connecting to the Submitty database to run queries. + +One way to run the query directly on the Submitty VM is to use the following command: `sudo su - postgres -c "psql -d submitty_f22_sample -XqAt -f explain.sql > analyze.json"` where `submitty_f22_sample` is replaced with the target database (see the [Database Design page](/developer/software_and_system_design/database_design) for info about the databases in Submitty), `explain.sql` is replaced with a text file that has your query in it, and `analyze.json` is the file that you want the query plan to be output to. + +#### Query Plan Visualization + +One method for profiling and visualizing queries is to use a query plan visualizer such as `https://explain.dalibo.com`. + +For this site, you generate a query plan for your query by prefixing your query with `EXPLAIN (ANALYZE, COSTS, VERBOSE, BUFFERS, FORMAT JSON)`, running it and pasting the output into the site along with your query (without the EXPLAIN prefix). The site then provides a visualization of your query, showing details such as the time it takes for individual parts of the query to run. + diff --git a/_docs/developer/development_instructions/plagiarism.md b/_docs/developer/development_instructions/plagiarism.md new file mode 100644 index 00000000..621f4622 --- /dev/null +++ b/_docs/developer/development_instructions/plagiarism.md @@ -0,0 +1,264 @@ +--- +title: Lichen Plagiarism Detection +category: Developer > Development Instructions > Advanced Development +redirect_from: + - /developer/plagiarism +--- + +See also [Instructor UI for Lichen Plagiarism Detection](/instructor/plagiarism). + + +### Lichen Configuration File + +Here is an example `config.json` file for a gradeable called +`example_gradeable` in course named `test_course` in `Fall 2017`, which +is found in the directory +`/var/local/submitty/courses/f17/test_course`: + +``` +{ + "semester": "f17", + "course": "test_course", + "gradeable": "example_gradeable", + "config_id": "1", + "version": "all_versions", + "regex": "README.txt, *.cpp", + "regex_dirs": [ + "submissions", + "results" + ], + "language": "plaintext", + "threshold": 20, + "hash_size": 5, + "other_gradeables": [ + { + "other_semester": "f16", + "other_course": "sample", + "other_gradeable": "example_gradeable" + } + ], + "ignore_submissions": [ + "grader", + "ta1", + "ta2", + "instructor", + "bitdiddle", + "aphacker" + ] +} +``` + + +The expected values for the configuration parameters are: + +* **"semester"** - a string, should be the same as the semester ID in + the course URL + +* **"course"** - a string, should be the same as the course ID in the + course URL + +* **"gradeable"** - a string, should be the same as the custom ID + given to the gradeable on which you want to run the plagiarism + detection + +* **"config_id"** - [optional] a string. If you wish for this + gradeable to show up on the plagiarism UI, make sure this string + is unique for each of the different runs of Lichen on this + gradeable + +* **"version"** - a string, can be either "all_versions", or + "active_version" + +* **"regex"** - a string of expressions separated by commas and + spaces, in which every string is a regular expression for a + submission file name to be included in the plagiarism detection + algorithm. To include all the submission files, put an empty + string here. + +* **"regex_dirs"** - an array of strings, can be any combination of: + "submissions", "results", "checkout", where each string should + appear at most once + +* **"language"** - a string, can be one of: "plaintext", "python", + "java", "cpp", "mips". + +* **"threshold"** - an integer, must be greater than or equal to 1 + +* **"hash_size"** - an integer, must be greater than or equal to 2 + +* **"other_gradeables"** - an array of objects that + represent gradeables whose submissions are to be included in + the matching algorithm, where each object contains: + * `other_semester` - the semester ID of the other gradeable + * `other_course` - the course ID of the other gradeable + * `other_gradeable` - the gradeable ID of the other gradeable + + If you wish to include no other gradeables, set to an empty array: `[]` + + +* **"ignore_submissions"** - an array of strings, where every string + is a user ID whose submissions are to be ignored in the plagiarism + detection algorithm. If you wish to ignore no one, leave it blank + (set to an empty array: `[]`) + +### Running the Lichen Test Suite + +Some parts of Lichen have automated tests which are run by GitHub Actions. +It is also possible to run the tests locally by navigating to `/usr/local/submitty/GIT_CHECKOUT/Lichen/tests` +inside your Vagrant virtual machine and running `python3 -m unittest discover`. +See more about automated testing on Submitty [here](/developer/testing). + + +### Running Lichen Manually + +To run plagiarism detection manually with custom a configuration, you +will need to log into the server and run the script: + +```bash +bash /usr/local/submitty/Lichen/bin/process_all.sh +``` + +`` should be a path to a directory containing +the `config.json` configuration file for this gradeable, e.g., +`...///lichen///`. + +`` should be a path to a directory containing the +semesters and the courses with their data, e.g., +`/var/local/submitty/courses`. This path is used to get +the submissions of the course users to be used in the plagiarism +detection algorithm, and, if configured so, to get submissions from +other courses in prior terms. + + +If the sample configuration file from the previous section is located in +`/var/local/submitty/courses/f17/test_course/lichen/example_gradeable/1`. To +run the script with this configuration file, we would run: + +```bash +bash /usr/local/submitty/Lichen/bin/process_all.sh /var/local/submitty/courses/f17/test_course/lichen/example_gradeable/1 /var/local/submitty/courses +``` + +#### Provided Code Files + +If you wish to include files to be used in the matching algorithm as +"instructor provided code", make sure to create the directory +`/provided_code/files/` and locate the files there. If +that directory does not exist, or if it contains no files, then the +matching algorithm will run without trying to compare student +submissions to "instructor provided code" files. + + +#### Editing and Re-running + +If you wish to edit the configuration settings, you can edit the +`config.json` file, and re-run the bash script with the same paths as +arguments. All of the existing output files of the previous run will +be automatically removed when re-running the script, except for the +configuration file and instructor provided code files, and the new run +would generate new output files. If you wish to add, change, or +remove the files that would be used as the "instructor provided code" +files, you would have to do so manually before re-running. + + +### Algorithm Overivew + +After a `config.json` file is made for a gradeable configuration with +the custom parameters, a job for it is placed in the +`daemon_job_queue` queue. When the job gets processed, the script +`process_all.sh` is run, which calls the following series of programs +that together produce the output for that configuration including +details of the types of matches found across student submissions: + +1. `concatenate_all.py`: gathers all the files that are to be compared +and searched for matches, as specified in the configuration file, and +outputs a `submission.concatenated` file for each submission + +2. `tokenize_all.py`: tokenizes each `submission.concatenated` file +and produces a `tokens.json` based on the language specified in the +configuration + +3. `hash_all.py`: hashes all the tokens in each `tokens.json` and +outputs its `hashes.txt` + +4. `compare_hashes.cpp`: uses the `hashes.txt` files to find matches +between all users and versions, to produce an `overall_ranking.txt` +files which contains the summary of all the submissions with the most +percent match, and individual `matches.json` and `ranking.txt` files +for every submission with suspicious matches. + +Besides the final output files produced by the fourth step, the other +intermediate output files of the programs are used in the Submitty web +UI, like the `submission.concatenated` and `tokens.json` which are +used to display the code block where users can see the matches. + +### Directory Structure + +Here is an overview of the directory structure relevant to processes +in Lichen runs: + +``` +⋮ +└── courses + └── {semesters} [e.g., "f15", "s16", "f16", "s17", ... ] + └── {courses} [e.g., "csci1100", "csci1200", ... ] + ├── submissions + ├── results + ├── checkout + └── lichen + ├── nightly_rerun.json + └── {gradeable} + └── {config_id} + | + ├── config.json + | + ├── logs + | └── lichen_job_output.txt + | + ├── provided_code + | ├── files + | | └── {files uploaded by instructor} + | └── submission.concatenated + | └── tokens.json + | └── hashes.txt + | + ├── other_gradeables + | └── {term}__{course}__{gradeable} + | └── {user} + | └── {version} + | ├── submission.concatenated + | ├── tokens.json + | └── hashes.txt + ├── users + | └── {user} + | └── {version} + | ├── submission.concatenated + | ├── tokens.json + | ├── hashes.txt + | ├── matches.json + | └── ranking.txt + | + └── overall_ranking.txt +``` + + +### Lichen Test Data and Development Debugging + +Checkout the companion LichenTestData repository before running +`vagrant up` to create the `Plagiarism` course which includes a suite +of development and regression test gradeables and submissions. Note: +Currently the LichenTestData repository is a private GitHub repository +for members of the Submitty GitHub organization. + +Most commonly, when developing and debugging Lichen repository files, you want to update your system with all the recent software changes. To do this, run: +```bash +install_lichen +``` +or: +```bash +bash /usr/local/submitty/GIT_CHECKOUT/Lichen/install_lichen.sh +``` +from anywhere inside your vagrant terminal. + +This command is similar to the `install_submitty` command which updates all Submitty software and dependencies, but it is only for installing or updating the parts relevant to Lichen. + +_See also: [Updating Dependencies](/developer/updating_dependencies) and [Development Instructions](https://submitty.org/developer/development_instructions)_ diff --git a/_docs/developer/development_instructions/sample_data.md b/_docs/developer/development_instructions/sample_data.md new file mode 100644 index 00000000..7c678926 --- /dev/null +++ b/_docs/developer/development_instructions/sample_data.md @@ -0,0 +1,75 @@ +--- +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) diff --git a/_docs/developer/development_instructions/trigger_functions.md b/_docs/developer/development_instructions/trigger_functions.md new file mode 100644 index 00000000..7634405c --- /dev/null +++ b/_docs/developer/development_instructions/trigger_functions.md @@ -0,0 +1,88 @@ +--- +title: Trigger Functions +category: Developer > Development Instructions +--- + +Trigger functions are a useful tool to keep data in sync. When a +database table's column is modified, a trigger function can be +set up to activate and modify the database as appropiate. + +We use PL/pgSQL for our trigger functions, which is a procedural +programming language part of PostgreSQL, the language our database +queries are conducted in. + +### Editing an Existing Trigger Function +To edit an existing trigger function, simply edit the appropiate file inside the +``migrations/migrator/triggers`` directory. When you next run ``submitty_install`` +or the migrator manually, the trigger functions on the database will be updated +with the changes to the code. + +### Creating New Trigger Functions +To create a new trigger function, + +1. First, navigate to the ``migrations/migrator/triggers`` directory. Then choose + between the ``master`` and ``course`` folder. Choose the ``master`` folder if + your trigger function is activated by changes to the master database, and similarly, + choose the ``course`` if your trigger function is activated by changes to the course + database. + +2. Create your file ``trigger_function_name.sql`` with these contents: + + ``` + -- + -- Name: trigger_function_name(); Type: FUNCTION; Schema: public; Owner: - + -- + + CREATE OR REPLACE FUNCTION public.trigger_function_name() RETURNS trigger + LANGUAGE plpgsql + AS $$ + BEGIN + (Body) + END; + $$; + + ``` + Replace the body with the trigger function. We recommend + [this tutorial series](https://www.postgresqltutorial.com/postgresql-triggers/introduction-postgresql-trigger/) + on how to write them. Check other trigger functions we have for an idea + on the syntax. One of the most important ideas to note is that OLD.column represents + the column's date before the edit and NEW.column represents the column's data after the + edit. + +3. Create a migration (see [here](/developer/development_instructions/migrations) + on how to write a migration). Somewhere in the migration, include the following: + + ``` + CREATE OR REPLACE FUNCTION public.trigger_function_name() + RETURNS trigger + LANGUAGE plpgsql + AS $$ + BEGIN + RETURN NEW; + END; + $$; + + CREATE TRIGGER some_name_about_your_trigger_function + BEFORE/AFTER UPDATE/INSERT/DELETE ON public.the_table_your_function_is_activated_by + FOR EACH ROW EXECUTE PROCEDURE public.trigger_function_name(); + ``` + There's a few things to break down here. Your trigger function can be actived before or after + a table has a deletion, an insertion, or a value update on it. Pick either ``BEFORE`` or ``AFTER``. Pick either ``UPDATE``, ``INSERT``, or ``DELETE``. If you want your function to be activated on, say, an update or an insertion, write instead + ``UPDATE OR INSERT`` in the spot above. + + Declaring the trigger function above is neccessary so that we can then + bind the trigger function to the appropiate action on the table. You do not need + the body to be blank, but we recommend it to be to avoid code duplication. + The blank body will be replaced by the migrator with the completed body in + your other file, so do not worry. + + It can be strategic to choose when in your migration you include the code above, + as you may want your trigger function binded only after a table is created. + +4. Make sure you include in the down migration section the deletion of the trigger function. + + ``` + DROP TRIGGER IF EXISTS + the_same_name_about_your_trigger_function + ON public.the_table_your_function_is_activated_by; + ``` diff --git a/_docs/developer/development_instructions/updating_dependencies.md b/_docs/developer/development_instructions/updating_dependencies.md new file mode 100644 index 00000000..f9a09fd0 --- /dev/null +++ b/_docs/developer/development_instructions/updating_dependencies.md @@ -0,0 +1,85 @@ +--- +title: Updating Dependencies +category: Developer > Development Instructions > Advanced Development +redirect_from: + - /developer/updating_dependencies +--- + +Within Submitty, we have a number of third-party dependencies to help augment the system. These +can be broken down largely into a couple of categories: + +1. Other Submitty Repositories +2. Third-Party Repositories +3. Third-Party Distributions +4. Third-Party Dependencies + +## Other Submitty Repositories + +While much of the code that makes up Submitty resides within the primary +[Submitty/Submitty](https://github.com/Submitty/Submitty) repository, there are some components +that reside outside of it. These include: + +1. [Submitty/AnalysisTools](https://github.com/Submitty/AnalysisTools) +1. [Submitty/Lichen](https://github.com/Submitty/Lichen) +1. [Submitty/RainbowGrades](https://github.com/Submitty/RainbowGrades) +1. [Submitty/Tutorial](https://github.com/Submitty/Tutorial) + +Each of these dependencies are installed/updated as part of the process of running INSTALL_SUBMITTY.sh, +which in-turn calls `.setup/bin/update_repos.sh` to either clone or update the repo as necessary. The +version that gets installed for each of these is defined in `.setup/bin/versions.sh`. Each of these +are cloned into `${SUBMITTY_INSTALL_DIR}/GIT_CHECKOUT/`. Additionally, we do download the +generated binaries for the appropriate version of Submitty/AnalysisTools into +`${SUBMITTY_INSTALL_DIR}/SubmittyAnalysisTools` to avoid the expensive process of getting the +whole stack toolchain to compile it on the spot. + +## Third-Party Repositories + +While the `GIT_CHECKOUT` folder mostly holds Submitty related repos, it does also contain these +third-party repos: + +1. [nlohmann/json](https://github.com/nlohmann/json) + +These repos are cloned under `${SUBMITTY_INSTALL_DIR}/GIT_CHECKOUT/vendor/`. Currently they are +not versioned. + +## Third-Party Distributions + +For autograding, Submitty relies on a handful of third-party tools to handle stuff like memory +analysis and test runners for some languages. These are: + +1. [DrMemory](https://drmemory.org/) +1. [Junit 4](https://junit.org/junit4/) +1. [JaCoCo](https://www.eclemma.org/jacoco/) + +The versions that we install of these is defined in `.setup/bin/versions.sh`. These are only +installed at initial system installation as part of `.setup/install_system.sh`. For +each of these, we download the compiled versions of the tool and then install into the +appropriate directory (e.g. `${SUBMITTY_INSTALL_DIR}/java_tools` for Java stuff, +`${SUBMITTY_INSTALL_DIR}/drmemory`). + +## Third-Party Dependencies + +To manage PHP dependencies, we use [composer](https://getcomposer.org/), and the packages it installs +can be found in [site/composer.json](https://github.com/Submitty/Submitty/blob/master/site/composer.json). + +To manage JS/CSS dependencies, we use [npm](https://npmjs.com), and the packages it installs can be found +in [site/package.json](https://github.com/Submitty/Submitty/blob/master/site/package.json). + +As Submitty is an application, not a library, each dependency in both of those files are pinned to a specific +version, and should not be set to use a range (e.g. use `1.0.0` over `^1.0.0`). + +For developing purposes, if there are code changes made to the packages managed by [npm](https://npmjs.com) ( +[Submitty/pdf-annotate.js](https://github.com/Submitty/pdf-annotate.js) for example), to view the changes locally: + 1. Clone the repo for the package into the Submitty VM. + 1. Run `npm install`. + 1. Run `npm run build`. + 1. Edit the `site/package.json` on the host machine to have the package point to the new directory temporarily. For example, + ``` + "@submitty/pdf-annotate.js": "file:///PATH/TO/THE/CLONED/REPO/IN/VM", + ``` + 1. Run the install script. + +For python dependencies, we use [pip](https://pip.pypa.io/en/stable/). These are installed currently only at +installation time, and not managed by Submitty currently. The current list of packages can be found in +[.setup/install_system](https://github.com/Submitty/Submitty/blob/master/.setup/install_system.sh). You should +search for "pip3 install" to find all things that pip installs. diff --git a/_docs/developer/development_instructions/vagrant_email_configuration.md b/_docs/developer/development_instructions/vagrant_email_configuration.md new file mode 100644 index 00000000..56d05d89 --- /dev/null +++ b/_docs/developer/development_instructions/vagrant_email_configuration.md @@ -0,0 +1,48 @@ +--- +title: Vagrant Email Configuration +category: Developer > Development Instructions +--- + + +When configured, Submitty can send instructor announcements and other +important messages to users via email. Please see the System Administrator +Documentation: [Email Configuration](/sysadmin/email_configuration) + +On the developer vagrant machine, the sending of emails is simulated with the +[nullsmtpd server](http://github.com/MasterOdin/nullsmtpd). + + + +1. The email configuration file, `/usr/local/submitty/config/email.json`, should contain: + + ```json + { + "email_enabled": true, + "email_sender": "submitty@myuniversity.edu", + "email_reply_to": "submitty_do_not_reply@myuniversity.edu", + "email_server_hostname": "localhost", + "email_server_port": 25 + } + ``` + + +2. Verify that the `nullsmtpd` daemon is running: + + ```bash + systemctl status nullsmtpd + ``` + If it is not running, run the following command to start it: + ```bash + systemctl start nullsmtpd + ``` + + +3. After performing an action on the website that should trigger + emails, you can check the contents of the `emails` table in the + master `submitty` database. + + And you can also inspect the logged messages for each user here: + + ``` + /var/local/submitty/logs/emails/mailboxes/ + ``` diff --git a/_docs/developer/end_to_end_tests.md b/_docs/developer/end_to_end_tests.md deleted file mode 100644 index 532d7224..00000000 --- a/_docs/developer/end_to_end_tests.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: End-to-End Tests -category: Developer -order: 9 ---- - -The _End-to-End Testing_ (e2e) suite is written in Python and tests -the pages by loading a webpage within the browser and confirming the -expected HTML is displayed. This does not test the PHP (or C++) code -directly, but rather focuses on user navigation through the website. - -The dependencies for this are -[nose2](https://pypi.python.org/pypi/nose2), -[unittest2](https://pypi.python.org/pypi/unittest2), and -[selenium](https://pypi.python.org/pypi/selenium). These can be -installed by doing: - -``` -pip install nose2 -pip install unittest2 -pip install selenium -``` - -This test suite runs within a Chrome browser so does require an -up-to-date local installation of Chrome. (This can be modified to use -a different browser stack by modifying the `setUpClass` method in -`tests/e2e/base_testcase.py`) - -You'll need to install the -[ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/getting-started). -Using HomeBrew on a Mac: - -``` -brew install chromedriver -``` - ---- - -To run the test suite: - -``` -nose2 --start-dir tests/e2e -``` - -To run an individual file: - -``` -nose2 --start-dir tests e2e.* -``` - -where `*` is the name of the test file to run. For example: - -``` -nose2 --start-dir tests e2e.test_access -``` \ No newline at end of file diff --git a/_docs/developer/getting_started/commit_to_PR_from_fork.md b/_docs/developer/getting_started/commit_to_PR_from_fork.md new file mode 100644 index 00000000..30ec50a2 --- /dev/null +++ b/_docs/developer/getting_started/commit_to_PR_from_fork.md @@ -0,0 +1,141 @@ +--- +title: How To Checkout and Commit to a PR from a Forked Repository +category: Developer > Getting Started +--- + +Contributors who are part of the Submitty organization on Github can +make new branches on our Github repositories and should make PRs from +a *branch directly within the Submitty repository*. External +contributors cannot make new branches on the Submitty repositories. +Instead, external contributors will clone/fork the Submitty repository +and then make a PR from *a branch on their forked repository*. + +It is simpler to review a PR made from a branch, and it is easy to +make small revisions as needed and commit and push those changes to +the branch. It is a little more work to do the same with a PR made +from a fork, but it is still possible -- *assuming that the owner of +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) + +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 + ``` + + Additionally, find the name of the fork on the fork's page on Github. + The `fork_name` may simply be `Submitty`, or the author may have chosen another name. + + Note: make sure your git credentials are set before pulling or pushing to a forked + repo. You can do this with the following commands. Use the `--global` flag if you + want to set this outside of just Submitty. + ``` + git config user.name "Your Name" + git config user.email "Your Email" + ``` + + +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): + + If you **are not** using ssh keys on git: + ``` + git checkout -b contributorusername-contributor_branch_name main + git pull https://github.com/contributorusername/fork_name.git contributor_branch_name + ``` + + If you **are** using ssh keys on git: + ``` + git checkout -b contributorusername-contributor_branch_name main + git pull git@github.com:contributorusername/fork_name.git contributor_branch_name + ``` + + +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. + + + +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: + + If you **are not** using ssh keys on git: + ``` + git remote add upstream https://github.com/contributorusername/fork_name.git + ``` + + + If you **are** using ssh keys on git: + ``` + git remote add upstream git@github.com:contributorusername/fork_name.git + ``` + + + Confirm that the upstream was set: + ``` + git remote -v + ``` + + Which should print something like this if you **are not** using ssh keys on git: + ``` + origin https://github.com/Submitty/Submitty.git (fetch) + origin https://github.com/Submitty/Submitty.git (push) + upstream https://github.com/contributorusername/fork_name.git (fetch) + upstream https://github.com/contributorusername/fork_name.git (push) + ``` + + Or this if you **are** using ssh keys on git: + ``` + origin git@github.com:Submitty/Submitty.git (fetch) + origin git@github.com:Submitty/Submitty.git (push) + upstream git@github.com:contributorusername/fork_name.git (fetch) + upstream git@github.com:contributorusername/fork_name.git (push) + ``` + + +6. Now once you are finished with your code changes, first commit them to + the local branch (named + `contributorusername-contributor_branch_name`). + + And then push them from your local branch to the external + contributor's fork and update the PR on github: + ``` + git push upstream contributorusername-contributor_branch_name:contributor_branch_name + ``` + + *NOTE: If you encounter a permissions error, it is possible that the external + contributor didn't grant access for collaboration on the branch.* + +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 + ``` + +--- + +See also [How to Make a Pull Request](make_a_pull_request) and +[How to Review a Pull Request](review_a_pull_request). diff --git a/_docs/developer/getting_started/edit_submitty_documentation.md b/_docs/developer/getting_started/edit_submitty_documentation.md new file mode 100644 index 00000000..1136a916 --- /dev/null +++ b/_docs/developer/getting_started/edit_submitty_documentation.md @@ -0,0 +1,24 @@ +--- +title: How To Edit Submitty Documentation +category: Developer > Getting Started +--- + +If you want to update or add documentation to Submitty.org here's what you do: + +1. If you haven't already, you'll need to clone the git repo of + Submitty.org: + + ``` + git clone https://github.com/Submitty/submitty.github.io.git + ``` + +2. After cloning the repo, go into the `_docs` folder. You will see a folder + representing each major category on Submitty.org + +3. Navigate to whichever page you want to edit and open it in your text editor of choice. + The files are written in Markdown. + +4. Run Jekyll locally to generate and view the webpages and proofread your edits: + [README.md](https://github.com/Submitty/submitty.github.io/blob/main/README.md) + +5. After you are done editing, you can submit a pull request for review. diff --git a/_docs/developer/getting_started/index.md b/_docs/developer/getting_started/index.md new file mode 100644 index 00000000..43ab731c --- /dev/null +++ b/_docs/developer/getting_started/index.md @@ -0,0 +1,89 @@ +--- +title: Overview +category: Developer > Getting Started +redirect_from: + - /developer + - /developer/index + - /developer/getting_started/ + - /developer/getting_started/index +--- + + + +## Suggestions for New Developers + +* Join our Community Discussion on Zulip: + [Contact Us](/contact) + +* You'll need to set up the full system on your own computer. The + easiest method is to + [run the system within a virtual machine (VM)](/developer/vm_install_using_vagrant). + Alternately, you can install the system natively on a dedicated + computer and allow outside access (which requires more steps to set + up networking, SSL/https, etc.) by following the + [complete system administrator instructions](/sysadmin/installation/index). + +* Read through the + [Student](/student/account/index), + [Grader](/grader/index), and + [Instructor](/instructor) + instructions and try it out. + +* Learn how to use git. + +* Browse our open [GitHub Pull Requests](https://github.com/Submitty/Submitty/pulls). + Pick an open PR and read the PR notes, linked issues, and other documentation. + Install the updated code on your VM, test the changes, and comment on or + [review the PR through GitHub](/developer/getting_started/review_a_pull_request) + + +* Look through our [GitHub Issues lists](https://github.com/Submitty/Submitty/issues) for some ideas + of problems to explore. + + * _**IMPORTANT NOTE**: We can only "assign" GitHub issues to users + who are already members of the Submitty GitHub organization. But + we are very happy to accept, review, and merge contributions from + outside of the organization. Students selected for Google Summer + of Code and active developers who already have multiple + contributions will be added to the Submitty GitHub organization._ + +* Learn what sections of the code are relevant for those issues (so + you’re not overwhelmed). + + * Hint: Use "git grep" to search for variables/filenames/specific + strings within the source files/directories. This can help you + locate relevant files. + +* Add & delete things to the code, re-install that portion of the + system and see what happens. See also [Development Instructions](/developer/development_instructions). + +* Use inspector, browser debugger, javascript console, etc. + + * Hint: It is helpful to set your javascript console errors to + be persistent (so they don't disappear when the page reloads). + E.g., in Chrome, you need to set "Console:Preserve log on + navigation", or in Firefox, "Enable persistent logs". + +* As you read the code, make a diagram for yourself of how the system + fits together. + +* Use jsfiddle (for testing or demoing new things). + +* Keep a work diary / log: what did you plan to do today, keep track + of how long it took you to do things, difficulties, how did you + solve it, helpful reference links, and what’s your plan for + tomorrow. + +* Get familiar with vagrant. + +* Run the relevant portions of test suite locally: + [Submitty Testing Instructions](/developer/testing/) + +* Submit a [Pull Request (PR)](/developer/getting_started/make_a_pull_request) + with your contributions. + +* Help by [Reviewing the Pull Requests](/developer/getting_started/review_a_pull_request) + of other developers. + +* [Improve the online documentation for Submitty](/developer/getting_started/edit_submitty_documentation). + diff --git a/_docs/developer/getting_started/make_a_pull_request.md b/_docs/developer/getting_started/make_a_pull_request.md new file mode 100644 index 00000000..8f22e77d --- /dev/null +++ b/_docs/developer/getting_started/make_a_pull_request.md @@ -0,0 +1,184 @@ +--- +title: How to Make a Pull Request +category: Developer > Getting Started +redirect_from: + - /developer/how_to_contribute + - /developer/getting_started/how_to_contribute +--- + +Be sure to read the [Suggestions for New Developers](/developer/getting_started/index). + +1. _In most cases_, a pull request (PR) should be addressing/closing + an [open issue](https://github.com/Submitty/Submitty/issues). + + _NOTE: You do not need to be formally assigned to an issue on + GitHub to make a pull request to contribute to Submitty! We + happily accept and review pull requests from contributors new to + our organization._ + + +2. Contributors from outside the Submitty GitHub organization should + clone/fork the repo on their own GitHub page, and create a branch with + the modifications to be included with this pull request (PR). + + _**IMPORTANT NOTE**:_ Please grant write access to the Submitty + organization administrators so we can more conveniently make small + edits (e.g., UI text wording changes). This will speed up the + approval and merging of your contributions. + + Contributors who are already active members of the Submitty GitHub + organization can make a branch within the Submitty organization + repo. _Note:_ This is the preferred method, since it allows other + members of the organization to directly push changes to the branch + (with fewer steps), and simplifies work as a group on larger features. + + PRs can be made from either type of branch. + + +3. Before submitting a PR or updating an existing PR, you should make + sure your code follows our [Style Guide](/developer/coding_style_guide) + and passes the relevant [tests](/developer/testing). + + +4. The PR title should be useful and descriptive. + + * Titles of PR, Issues, and commits should be <= 50 characters. + + * The PR title should not include the issue #. + + * To help developers, system administrators, and users who are + reading the release notes, please categorize your contribution + by formatting your PR title as follows: + + ``` + [:] + ``` + + Where `` is one of the following: + * `Bugfix`, + * `Feature`, + * `Refactor`, + * `Testing` (includes sample data), + * `Documentation`, + * `VPAT`, + * `UI/UX` (includes mobile, css), or + * `Dependency`. + + And `` is one of the following: + + * `Submission` (includes bulk uploads, teams, late days, notebook gradeables, and other student features), + * `Autograding` (includes router, container/docker), + * `Forum` (Includes Live Chat), + * `Notifications` (includes email and grade inquiries), + * `TAGrading` (includes PDF annotation, peer grading), + * `InstructorUI` (includes course and gradeable configuration), + * `SubminiPolls`, + * `HelpQueue`, + * `CourseMaterials`, + * `Plagiarism`, + * `RainbowGrades`, + * `Calendar`, + * `System` (includes installation, migrations, vagrant), + * `Developer`, or + * `API` + + And `` adds more specific details. + + _Note that `#` is appended to the title + automatically by GitHub when the PR is merged with "squash & + merge". Do not include this when you open a new pull request._ + + * If your PR is *Work In Progress*, please make a + [Draft Pull Request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) on GitHub. + This indicates to other developers and reviewers + that you'd like detailed feedback on your work, but it is incomplete. + When a PR is in the draft state it cannot be merged into the master branch. + + * **IMPORTANT:** If this PR requires system administrator action + before/after installation, the PR title should be prepended with + `[SYSADMIN ACTION]` and the commit message should describe the + specific actions required and include links to additional + documentation as appropriate. For example: + + ``` + [SYSADMIN ACTION][:] + ``` + + Most moderate database changes and software package + installation/updates should be handled automatically by + [migrations](/developer/development_instructions/migrations) and do not need to be flagged in this + way. However some operations, like edits to the Apache + configuration should not be performed automatically via a + migration because these files commonly have customizations that + make automation difficult or problematic. + 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/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. + + +4. The body of the PR should describe the purpose of the PR. + + * When merged, this PR body will be part of the documentation for + the + [next Submitty release](https://github.com/Submitty/Submitty/releases). + Thus, the contents should be + understandable to an average Submitty instructor user or system + administrator. The description can include links to related + issues or PRs, but this description should not require the user + to follow links to have a general understanding of the PR + purpose. + + * Include the string `Closes #1234` or `Fixes #1234` within the + top comment of the PR so that GitHub issue will be + automatically closed when the pull request is merged. + + * The commit message should talk about *WHAT* changed, and + *WHY*. Not *HOW*. How is the diff, and you don't need to repeat + it. + + * Comments explaining the code should be *in* the code, rather than in + the PR message or comments. + + * Developers are encouraged to test all user interface modifications with + [all available Submitty Themes](/student/account/theme): + e.g., light mode, dark mode, black mode, to ensure compliance/improvement + of [Web Accessibility](/developer/software_and_system_design/web_accessibility). + + * Including screenshots/videos in the issue or PR message is + helpful for UI changes -- both to solicit quick feedback from + reviewers and also to serve as documentation for the future + [release notes](https://github.com/Submitty/Submitty/releases). + + *NOTE: Please use light mode by default for all + screenshots/videos (this is our default theme). If your PR + includes a modification/bugfix related to the available + Submitty Themes (light mode vs. dark mode vs. black mode), + please also include comparison screenshots/videos for all + available themes.* + + * The comments should explain a bit about the + purpose/history/overview -- don't assume the reader knows it + (or link to the issue that explains everything). + + * Be explicit about what you want feedback on, or why you are asking + for specific reviewers. + + +--- + +See also [How to Review a Pull Request](review_a_pull_request). + +--- + +These guidelines drawn from: + +[https://www.atlassian.com/blog/git/written-unwritten-guide-pull-requests](https://www.atlassian.com/blog/git/written-unwritten-guide-pull-requests) + +[https://github.com/blog/1943-how-to-write-the-perfect-pull-request](https://github.com/blog/1943-how-to-write-the-perfect-pull-request) + +[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) + + diff --git a/_docs/developer/getting_started/pgadmin.md b/_docs/developer/getting_started/pgadmin.md new file mode 100644 index 00000000..618c6e10 --- /dev/null +++ b/_docs/developer/getting_started/pgadmin.md @@ -0,0 +1,36 @@ +--- +title: PGAdmin Setup Instructions +category: Developer > Getting Started > Advanced Setup +redirect_from: + -/developer/pgadmin +--- + + +* If you do not already have the PGAdmin app, please download and + install it: + + + + +* When the pgAdmin app loads, open `Add New Server` >> + `Create - Server`. + The name of the server can be whatever you would like, it + will not affect your connection. + +* Once configured, you will be able to use your server to access + information stored in the different databases associated with + Submitty, like that of an individual class. + + +* Once you have opened Navigate to the `Connection`sub-section. + The following parameters should be changed: + + * `Host name/address`: `localhost`. + + - If you get a connection timeout error, try `127.0.0.1` instead. + + * `Port`: `16442` + + * `Username`: `submitty_dbuser` + + * `Password`: `submitty_dbuser` diff --git a/_docs/developer/getting_started/phpstorm.md b/_docs/developer/getting_started/phpstorm.md new file mode 100644 index 00000000..e926aadb --- /dev/null +++ b/_docs/developer/getting_started/phpstorm.md @@ -0,0 +1,145 @@ +--- +title: PhpStorm Setup Instructions +category: Developer > Getting Started > Advanced Setup +redirect_from: + - /developer/phpstorm +--- + +Download at [https://www.jetbrains.com/phpstorm/](https://www.jetbrains.com/phpstorm/) + +--- + +First clone the repository and set up Vagrant. +Once you have that finished, open PhpStorm and make a `New Project from Existing Files` using the repository root as your project. +When prompted to select your scenario, select _Source files are in a local directory, no Web server is yet configured._ + +## Configure a SFTP connection + +Configuring a SFTP connection to your vagrant virtual machine allows PhpStorm to do thing like access the remote PHP +interpreter and deploy file changes automatically. +This step should be done first as this connection will be used in many of the later steps. + +Open `Tools` > `Deployment...` > `Configuration`. +Press the `+` and add a server of type `SFTP`. +Give the server a name, like _Submitty Vagrant_. +Set the following parameters under the `Connection` tab: + +- `SSH Connection`: create a new connection using `...` and then clicking on the `+` + - `Host`: `127.0.0.1` + - `Port`: `2222` + - `User Name`: `root` + - `Authentication Type`: `Key pair (OpenSSH or PuTTY)` + - `Private Key File`: `/.vagrant/machines/ubuntu-22.04/virtualbox/private_key` + - `Key Passphrase`: leave empty +- `Root Path`: `/usr/local/submitty` +- `Web server URL`: `http://localhost:1511/` + +Under the `Mappings` tab, set the following: + +- Press `Add Another Mapping` +- In the first mapping, set: + - `Local Path`: `` + - `Deployment Path`: `/` + - `Web Path`: leave empty +- In the second mapping, set: + - `Local Path`: `/site/public` + - `Deployment Path`: `/site/public` + - `Web Path`: `/` + +## Running code from vagrant + +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 `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. + +## Deploying updates automatically to vagrant + +Open `Tools` > `Deployment...` > `Options`. Set `Upload changed files automatically to the default server` to `Always`. Press `OK` to save this. + +## Enable PHP debugging using xdebug + +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`: `/site/public` +- `Deployment Server`: Use the SFTP connection you set up in the first step + +Press the `Validate` button to make sure the setup works. + +At this point you may see an error message that says ```Specified URL is not reachable, caused by: 'Request failed with status code 404'```. You may safely disregard this message. + +Follow instructions 2 - 4 on [this website](https://confluence.jetbrains.com/display/PhpStorm/Zero-configuration+Web+Application+Debugging+with+Xdebug+and+PhpStorm) to prepare PhpStorm for debugging and add bookmarklets to enable xdebug from your browser. + +## Connecting to the PostgreSQL database + +Open a database window by going to `View` > `Tool Windows` > `Database`. Press the `+` button and under `Data Source` choose to add a `PostgreSQL` database. Then set the following: + +- `Host`: `127.0.0.1` +- `Port`: `16442` +- `Database`: `submitty` +- `User`: `vagrant` +- `Password`: `vagrant` +- Check `Remember Password` + +Press `Test Connection` to verify that it works. Press `OK` to confirm adding the database. + +Next to the database name in the panel, there should be a label that says `1 of 6`. This is actually a button. Click it to see the other databases and turn on the check next to `submitty_s18_sample` to show that database in the list. Press the refresh arrows and some schemas should appear under `submitty_s18_sample`. Click the check next to the `public` schema to show it in the list. + +Now you can browse the tables in the database window by expanding the tabs next to the `public` schema. Double click on any table to see and edit its contents. + +## Running PHPUnit tests + +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` +- Hit the arrows button to confirm that it can find PHPUnit +- `Default Configuration File`: `/usr/local/submitty/GIT_CHECKOUT/Submitty/site/phpunit.xml` + +Press `OK` to save the test configuration. + +Then you need to add a run configuration for PHPUnit. Open `Run` > `Edit Configurations`. Press the `+` button and add a `PHPUnit` configuration. Set: + +- `Test Scope`: `Defined in the configuration file` +- `Use alternative configuration file`: Unchecked + +Press `OK` to save the test run configuration. You should be able to run it as normal (or even with coverage!) from the `Run` menu. + +## Debugging JavaScript in PhpStorm + +This one is not as guaranteed as the others. Make sure you have already ran the `Deploying updates to vagrant` steps. +Also, you need to use Google Chrome for this. + +You'll need to install [the JetBrains IDE Support](https://chrome.google.com/webstore/detail/jetbrains-ide-support/hmhgeddbohgjknpmjagkdomcpobmllji) plugin for Chrome. Then, after navigating to the page with the JavaScript you want to debug, right click the extension and press `Inspect in PhpStorm`. If it decides to work, you'll see a banner in Chrome that says `"JetBrains IDE Support" is debugging this browser`. Note that closing the banner will disconnect the debugger so you'll have to leave it up. + +Then, you should be able to set breakpoints in your JavaScript files in PhpStorm and debug them. + +#### If that doesn't work + +Alternatively, you can debug in Chrome by using a custom run configuration. Open `Run` > `Edit Configurations`. Press the `+` button and add a `JavaScript Debug` configuration. Set: + +- `URL`: `http:/localhost:1511` +- `Browser`: `Chrome` (only option currently) +- `Ensure breakpoints are detected when loading scripts`: Leave unchecked unless you're debugging some code that runs on page load + +In the `Remote URLs of local files (optional)` section, find `site/public` and give it a `Remote URL` of `http://localhost:1511`. + +Press `OK` to save the run configuration. If you then `Debug` the configuration, it should open a new Chrome process and automatically start debugging, note that this Chrome will not have any of your user data / configuration / extensions. Note that if you `Run` the configuration you will not be able to debug JavaScript. + +## Making debugging less annoying + +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 `PHP` > `Debug` > `Step Filters`. Check `Skip magic methods` and add the following to `Skipped Methods`: + +- `app\views\AbstractView->__construct` +- `app\models\AbstractModel->convertName` +- `app\models\AbstractModel->__call` +- `app\libraries\Utils::startsWith` +- `app\models\AbstractModel->app\models\{closure}` + +Add the following to `Skipped Files`: + +- Hit the `...` and navigate to `site/vendor/composer/ClassLoader.php` diff --git a/_docs/developer/getting_started/project_ideas.md b/_docs/developer/getting_started/project_ideas.md new file mode 100644 index 00000000..7066fc04 --- /dev/null +++ b/_docs/developer/getting_started/project_ideas.md @@ -0,0 +1,357 @@ +--- +title: Project Ideas +category: Developer > Getting Started +redirect_from: + - /developer/project_ideas +--- + + +[comment]: <> We are thrilled to announce that Submitty has been accepted to [Google +[comment]: <> Summer of Code (GSoC) 20XX](https://summerofcode.withgoogle.com/). +[comment]: <> See [Submitty GSoC Application & +[comment]: <> Reports](/developer/google_summer_of_code/index) for more information +[comment]: <> about the application process and to read reports from Submitty GSoC +[comment]: <> contributors in past summers. + +[comment]: <> Submitty has been a participating organization of [Google Summer of +[comment]: <> Code](https://summerofcode.withgoogle.com/) for six successful +[comment]: <> seasons. [We have applied for selection for Summer 20XX](/developer/google_summer_of_code/index) +[comment]: <> and our +[comment]: <> Project Ideas list below has been updated. The organizations selected +[comment]: <> for Summer 20XX Google Summer of Code will be announced in late +[comment]: <> February. + +The project ideas listed below target a variety of different topics +and require different levels of prior experience. The scope of these +projects varies, and may require different overall time commitments +(varying full-time-work-equivalent from 1 month to 3 months). We are +also interested in project proposals based on other topics from our +list of open bugs and feature requests. Submit questions or comments +on specific issues through our [Submitty GitHub Issue +Tracker](https://github.com/Submitty/Submitty/issues) and +join +our [Zulip server](/contact) to meet the Submitty mentors and other new +developers. + + +  + + +1. **Interactive User Interfaces With Vue.js** + + Submitty primarily uses server-side rendering via Twig. jQuery is + used extensively throughout the site to add interactivity, but it + is insufficient for the most complex pages. Instead, we think + Vue.js is a better path forward for pages such as the TA grading + interface, discussion forum, office hours queue, and rainbow grades + customization interface. The goal of this project is to explore + how we can add and improve interactivity to specific pages and + support future development efforts involving the use of Vue.js + within Submitty's codebase. + + _Expected Outcomes_: This project is flexible in both scope and size. + A successful proposal should include detailed information about the + specific pages and components to be converted, including time estimates + for the proposed conversion projects and common core logic improvements. + Participants will gain a better understanding of the challenges involved + in introducing new technologies to a large existing codebase, gain + experience architecting a key part of a large project, and grow their + knowledge of modern web frameworks. + + [Ongoing Work to Incorporate Vue.js](https://github.com/Submitty/Submitty/pulls?q=is%3Apr+vue+is%3Aclosed+) + [Open Issues related to Vue.js](https://github.com/Submitty/Submitty/issues?q=is%3Aissue%20state%3Aopen%20vue%20) + + _Skills & Experience Required_: Moderate to advanced programming + skills, preferably with experience using modern client-side web + frameworks. + + _Possible Mentors_: William Allen, Shail Patel, Chris Reed, Barb Cutler + _GSoC Project Size_: 175 or 350 hours + _Difficulty Level_: medium to challenging + +   + + + +2. **Expand Testing of the Manual/TA Rubric Grading Interface** + + [Overview of Rubric Grading Interface](/grader/rubric_grading/index) + + Our TA grading interface is elaborate, highly-featured, and + customizable. However, the interface is visually overwhelming to + new graders and some of our TA grading features are not adequately + tested by automated unit and end-to-end (Cypress) regression testing. + + [Open Issues related to TA Grading](https://github.com/Submitty/Submitty/issues?q=is%3Aopen+is%3Aissue+label%3A%22TA+Grading+%2F+TA+UI%22) + [Open Issues related to Sample Data](https://github.com/Submitty/Submitty/issues?q=is%3Aopen+is%3Aissue+label%3A%22Sample+Data%22) + [Related Prior GSoC Project: Cameron Peterson](/developer/google_summer_of_code/2023_Cameron_Peterson) + [Related Prior GSoC Project: Rahul Vishwakarma](/developer/google_summer_of_code/2024_Rahul_Vishwakarma) + + _Note: This project may be combined with the previous project idea._ + + _Expected Outcomes_: The primary goals for this project include the + expansion of our automated testing of the TA Grading pages and to + patch bugs uncovered by this improved testing. The project may be + expanded in scope to additionally propose and execute small or + modest user interface revisions that enhance the TA experience, + especially for graders who are new to the interface and grading + process. + + _Skills & Experience Required_: Some programming experience, + willingness to learn web and database development and the Cypress + end-to-end automated testing framework. Having served as a + teaching assistant with grading experience design will be + beneficial. + + _Possible Mentors_: William Allen, Cameron Peterson, Barb Cutler + _GSoC Project Size_: 90 or 175 hours + _Difficulty Level_: introductory to medium + +   + + +3. **Refactor and Performance Improvements for the Manual/TA Rubric Grading Interface** + + [Overview of Rubric Grading Interface](/grader/rubric_grading/index) + + _Note: This project may be combined with one of the previous project ideas._ + + The Manual/TA rubric grading interface is elaborate, + highly-featured, and customizable; however, the performance of + these webpages is problematic for large courses due to inefficient + database queries and server communication delays to load data that + could/should be asynchronous. The manual/TA rubric pages could + benefit from a significant technology refactor to use Vue/Vite, for + example. + + [Open Issues related to TA Grading](https://github.com/Submitty/Submitty/issues?q=is%3Aopen+is%3Aissue+label%3A%22TA+Grading+%2F+TA+UI%22) + + _Expected Outcomes_: This project would first prepare a detailed + software design plan for an organized, multi-stage incremental + refactor of the manual/TA rubric pages and follow with the + execution/implementation of a significant portion of the new + design. The project could include the extension and/or updating of + our automated end-to-end (Cypress) testing and patching bugs + uncovered by this testing (as described in the previous project + idea). The project should include benchmarking along the way to + ensure that the refactor is improving the performance of the + Manual/TA Rubric Grading interface. The general interface for + TA/Manual grading should remain similar, but the project may + include small user interface revisions. + + _Skills & Experience Required_: Web and database development + experience and general software design and implementation + experience. Experience with end-to-end automated testing (Cypress) + and and having served as a teaching assistant with grading + experience design is beneficial but not required. + + _Possible Mentors_: William Allen, Barb Cutler + _GSoC Project Size_: 175 or 350 hours + _Difficulty Level_: medium to challenging + +   + + +4. **Notebook Builder: UI To Streamline Instructor Configuration of Automated Grading** + + Our system for automated testing and grading of student work is + very powerful, but the configuration process that instructors must + navigate is complex and time-consuming. While we provide a number + of examples, the number of choices for development of an + autograding configuration is overwhelming. The primary method for + creating an autograding configuration is to prepare a `config.json` + file (and any necessary additional files) and upload or store these + files on the server file system. We have a prototype Web GUI + interface we call the "Notebook Builder" but the current state of + the feature is undocumented and functionality is limited. We + would like to improve and expand this feature to facilitate + instructor creation of basic and moderate complexity autograding + configurations. + + [Assignment Autograding Configuration Instructions](/instructor/autograding/specification) + [Notebook Assignment Configuration](/instructor/assignment_configuration/notebook) + [Tutorial Autograding Configuration Examples](https://github.com/Submitty/Tutorial/tree/main/examples) + + This project will involve multiple modules of Submitty including + web UI development, integration, documentation, additional tutorial + examples, and extending output generation to instructor solutions + in compiled languages. + + [Open Issues related to Autograding](https://github.com/Submitty/Submitty/labels/Autograding) + [Open Issues related to Notebook / Notebook Builder](https://github.com/Submitty/Submitty/issues?q=is%3Aopen+is%3Aissue+label%3A%22Notebook+%2F+Notebook+Builder%22) + [Related Prior GSoC Project: Sahil Suman](/developer/google_summer_of_code/2024_Sahil_Suman) + + _Expected Outcomes_: The primary focus of the project is the + revision and expansion of the Notebook Builder UI to increase the + number of autograding features that are supported. The UI should + be easy-to-use for instructors of + non-computer-science/non-programming courses and also instructors of courses with + introductory to moderate programming assignments. The size and + scope for a proposal in this area is flexible, depending on the + time commitment and prior skills of the applicant. + + _Skills & Experience Required_: Some programming experience, + willingness to learn web and database development. Prior + experience with user interface design and an eye for quality user + design are beneficial. Having served as a teaching assistant or + instructor with experience in programming assignment design will be + beneficial but not required. + + _Possible Mentors_: Barb Cutler, Chris Reed + _GSoC Project Size_: 90 or 175 or 350 hours + _Difficulty Level_: introductory or medium + +   + +5. **Expansion of Examples and Documentation of Intermediate and Advanced Autograding Features** + + _Note: This project is related to previous project idea but is a distinct project._ + + Our system for automated testing and automated grading of student + work is very powerful and highly-customizable, but the + documentation for our moderate and advanced autograding features is + incomplete. While we provide a number of autograding examples, + some of the examples are out-of-date and do not represent our + current suggested best practices. + + [Assignment Autograding Configuration Instructions](/instructor/autograding/specification) + [Submitty Autograding Tutorial Examples](https://github.com/Submitty/Tutorial) + [Additional Autograding Examples](https://github.com/Submitty/Submitty/tree/master/more_autograding_examples) + [Related Prior GSoC Project: Drumil Patel](/developer/google_summer_of_code/2019_DrumilPatel) + + We would like to reduce the learning curve for new instructors and + provide more tutorial examples of autograding for instructors + teaching courses of any level. Automated testing and automated + grading can be used in introductory programming courses in middle + and high schools, including AP Computer Science. It can also be + used by programming-intensive intermediate and upper level / senior + university-level systems coursework. Assignments that require can + be configured with custom Docker Images to provide access to + specific programming languages and libraries. + + [Open Issues related to Docker Image Autograding](https://github.com/Submitty/Submitty/issues?q=label%3A%22Docker+Container+Autograding%22+) + [Docker Images for Autograding Common Programming Languages](https://github.com/Submitty/DockerImages/tree/main) + [Example Custom Docker Images University ](https://github.com/Submitty/DockerImagesRPI/tree/main/dockerfiles) + [Sample Java Assignments](/instructor/autograding/sample_assignments) + [Related Prior GSoC Project: Nithish Reddy Banda](/developer/google_summer_of_code/2024_Nithish_Reddy_Banda) + + _Expected Outcomes_: The project should begin with a review and + organization of existing sample and tutorial assignments and + current autograding functionality documentation. Out-of-date or + underdeveloped autograding configuration examples should be + expanded as necessary, and features that are missing documentation + and examples should be identified (e.g., generated random input and + output from instructor solution, customized docker containers, + autograding graphical output, autograding) and resolved by creating + new examples. Finally, we would like to create and support a + resource for the community of crowd-sourced complete programming + assignments/exercises with included autograding configuration. + + _Skills & Experience Required_: Moderate to advanced programming + experience, willingness to learn web and database development. + Having served as a teaching assistant or instructor with experience + in programming assignment design will be beneficial. + + _Possible Mentors_: Shail Patel, Chris Reed, Barb Cutler + _GSoC Project Size_: 175 or 350 hours + _Difficulty Level_: medium to challenging + +   + + + +6. **AI/ML to Enhance and Streamline Manual / TA Grading** + + The use of a unified and retroactively editable rubric for + manual/TA grading can ensure consistency when grading large + courses, especially when more than one grader is working on a + single problem or assignment. However, it is usually still + necessary for the graders to inspect the student work one-at-a-time + and it can be difficult for the grader to remember the details of + all previously graded assignments and recognize patterns that + should be graded similarly. Furthermore, the process of manual + grading is time-consuming and thus detailed and thoughtful + constructive feedback to each individual is often not possible. + + [Overview of Rubric Grading Interface](/grader/rubric_grading/index) + + The goal of this project is to explore the potential to leverage + Artificial Intelligence and Machine Learning (AI/ML) to reduce the burden + of manual grading in large courses with either programming or + non-programming assignments. Automatically organizing student + submissions into groups that contain similar patterns and have + common strengths or flaws can ensure that student work is assessed + consistently and students receive appropriate and in-depth + feedback to aid their learning. + + The Submitty project includes related technology for the static + analysis of student's code and tools to screen for plagiarism in + both student-submitted plain text assignments and software. Note + that the Submitty static analysis and plagiarism tools have been + tested and validated with datasets of sample student submissions; + however, for privacy and confidentiality reasons, these datasets are + not and cannot be part of the Submitty open-source materials. + + [Autograding using Static Analysis](/instructor/autograding/static_analysis/index) + [Plagiarism Detection](/instructor/course_management/plagiarism) + + _Expected Outcomes_: Detailed design plan for the integration of an + AI/ML framework into Submitty for the analysis and clustering the + assignment submissions by students based on common patterns in the + text and/or code. Implementation of a prototype AI/ML tool to + detect common patterns in student submissions and present this + information to the grader in an organized way to allow streamlined + bulk grading and feedback within the manual/TA grading interface. + As time permits (and based on the scope and time commitment) + evaluation of the effectiveness of this technique on real world + data and the potential for improving the efficiency of the + manual/TA grading process and the quality/accuracy and quantity of + useful constructive feedback to students. + + _Skills & Experience Required_: Coursework and/or professional + experience in AI/ML and modern AI/ML technology. Moderate to + advanced programming experience, and willingness to learn web and + database development. Having served as a teaching assistant for a + large course with manual grading experience design will be + beneficial. + + _Possible Mentors_: Barb Cutler, William Allen + _GSoC Project Size_: 175 or 350 hours + _Difficulty Level_: medium to challenging + +   + + +7. **Other Topics** + + The Submitty team welcomes GSoC project proposals on other topics + related to items in our GitHub issue tracker. A successful + application would select one or more issues of moderate scope + proportional to the applicant's time commitment and prior + experience. Be sure to join our [Zulip server](/contact) to meet + the Submitty mentors and other new developers and discuss your + interests and project plans. + + _Skills & Experience Required_: Some prior programming experience, + willingness to learn web and database development, and additional + specific skills as appropriate. + + _Possible Mentors_: Barb Cutler, William Allen, Shail Patel, Cameron Peterson, Chris Reed, Matthew Peveler, Preston Carman + _GSoC Project Size_: 90 or 175 or 350 hours + _Difficulty Level_: introductory to medium to challenging + +  + +See also: + +* [Submitty GitHub Issue Tracker](https://github.com/Submitty/Submitty/issues) + +* [Developer](/developer) pages + +* [Review a Pull Request](/developer/getting_started/review_a_pull_request) + +* [Make a Pull Request](/developer/getting_started/make_a_pull_request) + +* [Edit Submitty Documentation](/developer/getting_started/edit_submitty_documentation) + + diff --git a/_docs/developer/getting_started/review_a_pull_request.md b/_docs/developer/getting_started/review_a_pull_request.md new file mode 100644 index 00000000..6085485d --- /dev/null +++ b/_docs/developer/getting_started/review_a_pull_request.md @@ -0,0 +1,117 @@ +--- +title: How To Review a Pull Request +category: Developer > Getting Started +--- + + +You've been asked to review another developer's work, which has been +posted to GitHub as an open [pull request (PR)](https://github.com/Submitty/Submitty/pulls). +What do you need to do? + +1. Read the [Suggestions for New Developers](/developer/getting_started/index). + +2. Make sure you understand the purpose of the PR. Read the notes in + the PR and read the notes from any issues that are referenced in the + PR. + + * *What bug(s) is the PR attempting to fix?* + + If it's a bug, it's a good idea to try to reproduce the problem from + the current main branch. Make sure you understand the sequence of + actions needed to produce the erroneous behavior. + + * *What new feature(s) is the PR adding?* + + If it's a new feature, make sure you understand the purpose of the + new feature and how it's supposed to work. As needed, test the current + main branch to understand how the system works without the new feature. + + +3. Checkout the branch containing the bug fixes and/or new feature. + + * If the PR is a branch of the main Submitty repository, you can + check it out with + + ``` + git checkout BRANCH_NAME + ``` + + * If the PR is from a fork of the main Submitty repository, first + create a new branch based of the pull request ID (PR_ID). The new branch + will be called BRANCH_NAME in this example + + ``` + git fetch origin pull/PR_ID/head:BRANCH_NAME + ``` + + Then, checkout the new branch. + + ``` + git checkout BRANCH_NAME + ``` + + Now you have a version of the code in a new branch on the main repo. + Review the PR normally and delete the temporary branch when you are done + + * If you need to make edits to a PR made from a branch in a forked + repo, see: + [How to Checkout and Commit to a Fork PR](commit_to_PR_from_fork) + + +4. [Re-install the system](/developer/development_instructions/index) + as necessary + + +5. Test the system with typical use cases. Think about how a novice + user will experience this portion of the Submitty system. Is it + clear and intuitive? Are the instructions (on page or on + submitty.org) clear? As appropriate leave comments for the PR + author with specific suggestions for improvement. + + Test the system with extreme use cases or corner cases. Try to + break the overall system or new feature. If you find an error, + leave a comment in the PR describing how to reproduce the problem. + + +6. Look through the source code for the pull request. Depending on + your familiarity with this portion of the code, your review may be + cursory or in depth. + + * Does the new or modified code have adequate comments? + + * Is the code well structured into functions and/or classes? + + * Has the PR introduced code duplication? Should the code make use + of existing functions/classes? Or modify existing functions with + new parameters so code sharing is feasible? + + * Critique code for security-related vulnerabilities. + + * Critique code for programming language-specific coding & style + conventions. + + * Does the PR require system level changes or database updates to + work with older, existing installations? Does the PR include + necessary changes to automate these updates using + a course or system-wide + [Migration](/developer/development_instructions/migrations)? + + + +7. Is the PR title appropriate? Are the PR notes sufficient? Will a + system administrator understand the purpose & importance of + installing this commit on their system? + + +8. Through the github review system, leave feedback and comments and + indicate whether you approve as is + or require changes on this PR before it can be merged. + + If you have indicated that changes are necessary, be prompt in + following up with the PR author as the changes are made, and + hopefully, in short order, approving that the code be merged into + the main branch. + +--- + +See also [How to Make a Pull Request](make_a_pull_request). \ No newline at end of file diff --git a/_docs/developer/getting_started/vm_install_using_vagrant.md b/_docs/developer/getting_started/vm_install_using_vagrant.md new file mode 100644 index 00000000..d1356635 --- /dev/null +++ b/_docs/developer/getting_started/vm_install_using_vagrant.md @@ -0,0 +1,625 @@ +--- +title: VM Install using Vagrant +category: Developer > Getting Started +redirect_from: + - /developer/vm_install_using_vagrant +--- + +The instructions below will setup an instance of Submitty on your own +hardware that will have several courses, many sample assignments, and +a hundred students with assignment submissions so you can explore the +features of Submitty as it would appear "mid-semester". Your host +computer can run any modern operating system (Windows, Mac, or +Unix/Linux). The installation process will create a new Virtual +Machine (VM) on your computer and the VM will use the Ubuntu GNU/Linux +operating system. + +***NOTE:** We only officially support and test development using +VirtualBox for AMD and Intel machines and QEMU for +M-Series ARM MacOS machines.* + +--- + +## Pre-Installation Checklist + +1. To develop with a Virtual Machine (VM), your computer should have + at least 8GB of RAM and a 64-bit host OS. AMD-V or Intel VT-x are + also required (most computers have these). Submitty is RAM and I/O + intensive, so more RAM and a fast disk are better. + +2. Make sure you have at least 65GB of hard disk available for + installation. We do not recommend installing the Submitty + Developer VM on DropBox, OneDrive, GoogleDrive, or other cloud + storage. + +3. Some developers have had problems running both VirtualBox and + VMWare on the same computer. If you have problems, we suggest + shutting down the VMWare VMs, or stopping the VMWare services, or + uninstalling VMWare. + +4. If you're running Windows, it is recommended to disable Hyper-V. + Leaving it enabled will force VirtualBox to use the Hyper-V + backend, which will be slower and can cause instability in the + VM. + + ***NOTE:** This may stop programs like Docker Desktop and WSL 2 from + working. If these programs are essential to your workflow, consider + looking up how to add a separate boot entry with "hypervisorlaunchtype" + set to "off" for use with VirtualBox.* + + ***NOTE:** Installing WSL2 may also reconfigure your OS to use Hyper-V or Windows hypervisor + platform and prevent VirtualBox from working correctly. It is recommended to not install + or use WSL2 alongside VirtualBox for now.* + +5. If you're on an M-series ARM MacOS (e.g., M1, M2, M3), + you will be using QEMU with SMB file sharing. + To enable this, open **System Settings** and navigate to **General > Sharing**. + Press the (i) button next to **File Sharing**, and in the popup window + click "Options...". Then turn on "Share files and folders using SMB" and + check the box next to your name in the list below. + +6. The complete installation process could take an hour or more and + will probably fail if paused or interrupted. Make + sure your internet connection is strong and consistent. You'll + probably want to plug in your laptop power cord. Check your + computer settings and make sure the machine does not hibernate or + go to sleep during installation. + +--- + +## Submitty Developer VM Installation + + +1. ENABLE VIRTUALIZATION + *Follow the instructions below specific to your host operating system:* + + * **MacOS** + *Virtualization is generally enabled by default.* + + * **Windows 10** + 1. Open the **Settings** app by searching for it in the windows bar or clicking it in the Windows menu. + 2. Navigate to **Update and Security**, then select **Recovery** from the side menu. + 3. Under **Advanced Startup**, click **Restart Now**. + 4. Once your PC has rebooted, click the **Troubleshoot** option. + 5. Click **Advanced Options**. + 6. Click **UEFI Firmware Settings** and restart as suggested. + 7. Enter your **BIOS** (generally by pressing Del, F12, or other keys while booting). + If you are not able to find the key combo needed to enter your BIOS, + refer to [this guide](https://www.tomshardware.com/reviews/bios-keys-to-access-your-firmware,5732.html). + 8. Locate **Virtualization**, and enable it. + (Note: Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool. + If you cannot find the option to enable virtualization, + [search Google](http://tinyurl.com/enable-virtualization) + for a tutorial on enabling it with your motherboard.) + 9. Reboot your computer. + + * **Windows 11** + 1. Open **Change advanced start-up options** by searching for it in the search bar. + 2. Under **Advanced Startup**, click **Restart Now**. + 3. Once your PC has rebooted, click the **Troubleshoot** option. + 4. Click **Advanced Options**. + 5. Click **UEFI Firmware Settings** and restart as suggested. + 6. Locate **Virtualization**, and enable it. + (Note: If you cannot find the option to enable virtualization, + [search Google](http://tinyurl.com/enable-virtualization) for a tutorial on enabling it with your motherboard.) + 7. Reboot your computer. + + * **Ubuntu** + 1. Enter your **BIOS** (generally by pressing Del, F12, or other keys while booting). + 2. Navigate the **BIOS Settings**. + 3. Locate **Virtualization** and enable it. (Some motherboards may call it SVM, AMD-V, VT-x/Vanderpool) + 4. Be sure to choose **Hardware Virtualization** in the **System -> Acceleration** + settings of the virtual machine you are using. + 5. **NOTE:** If using secure boot, Vagrant may fail to work with VirtualBox. + You will then either need to disable secure boot from the boot menu/BIOS or + follow [these steps](https://era86.github.io/2018/01/24/vagrant-virtualbox-secureboot-in-ubuntu-1604.html) + to self-sign the necessary packages to run Vagrant and VirtualBox. + +2. DOWNLOAD AND INSTALL THE LATEST DEPENDENCIES + *Follow the instructions below specific to your host operating system* + + * You will need: + * [Ruby](https://www.ruby-lang.org/en/downloads) + * [Git](https://git-scm.com/downloads) + * [Vagrant](https://developer.hashicorp.com/vagrant/install) + * *M-SERIES ARM MacOS:* [QEMU](https://www.qemu.org) + * *EVERYONE ELSE:* [VirtualBox](https://www.virtualbox.org/wiki/Downloads) + * Ensure VirtualBox version is compatible with Vagrant. + + + * **MacOS** + You can either go to respective sites and download the necessary binaries or + install [Homebrew](http://brew.sh/), if you don't have it, and then: + + If you have an M-series ARM Mac, run: + ``` + brew install --cask vagrant + brew install qemu + vagrant plugin install vagrant-qemu + ``` + + Or if you have an older Intel-based Mac, run: + + ``` + brew install --cask vagrant + brew install --cask virtualbox + ``` + + * **Windows** + Download the latest Vagrant AMD64 binary for windows. + *As of Vagrant version 2.4.7, Virtualbox 7.1.10 is compatible.* + + * **Ubuntu/Debian** + + * The Ubuntu repository does not contain the latest version of + Vagrant or VirtualBox and using them may not work nor are they + supported. We recommend that you either download the necessary + binaries from their respective steps or follow the steps + outlined below for each: + + VirtualBox: + + Vagrant: + (if that doesn't work, try: ) + + * **Fedora/Red Hat Linux** + + * For Fedora, the latest version of VirtualBox is recommended to + prevent errors. Download the RPM from the VirtualBox + website. Make sure your version of Fedora is up to date using: + ``` + sudo dnf update + sudo dnf upgrade + ``` + + and then inputting your password when prompted. + Then install the Virtual Box rpm using: + ``` + sudo dnf install VirtualBox-xxxxx.rpm + ``` + + Install Vagrant using: + ``` + sudo dnf install vagrant + ``` + + * **Common errors when running vagrant up (Fedora/RHEL)** + + 1. Missing virtnetworkd: + Enable it in your terminal by running: + ``` + sudo systemctl start virtnetworkd + ``` + + 2. If your vagrant ever freezes kill it with + ``` + VBoxManage controlvm VM_NAME poweroff + ``` + or if that doesn't work, reboot the computer and then + run `vagrant destroy` before re-running `vagrant up --provider=virtualbox` again. + + +4. CLONE THE [SUBMITTY REPOSITORY](https://github.com/Submitty/Submitty) + + * Clone it to a location on your computer (the "host"). + + ``` + git clone https://github.com/Submitty/Submitty.git + ``` + + ***NOTE:** If you are not currently part of the Submitty organization on GitHub, you may want to + [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) + the repo and use the git url from your fork instead, especially if you are looking to + contribute. You will then make PRs to the main Submitty repository from branches on your fork.* + + + * **OPTIONAL:** If you will be developing code in one of the companion + Submitty repositories (e.g., AnalysisTools, Lichen, + Localization, RainbowGrades, Tutorial), also clone those + repositories to the same directory. For example: + + ``` + home + └── myusername + └── Submitty + └── GIT_CHECKOUT + ├── AnalysisTools (optional) + ├── Lichen (optional) + ├── Localization (optional) + ├── RainbowGrades (optional) + ├── Submitty + └── Tutorial (optional) + ``` + + *This host directory structure will be shared / synced between + your host operating system and the Submitty virtual machine.* + + +5. RUN VAGRANT + + + * Navigate into the Submitty repository on your computer in a + shell/terminal. *On Windows, run CMD or PowerShell on administrator mode.* + + + * **Build pre-packaged VM** + + *NOTE: The pre-packaged Submitty VM is not (yet) + available for QEMU / M-Series ARM Mac machines.* + + If you are using VirtualBox as your provider, you will by default + use a pre-packaged Submitty VM. This will have all of Submitty + already setup. This is a recently built machine, + but it may be slightly older than the current + [main branch on GitHub](https://github.com/Submitty/Submitty). + + + To create the virtual machine from the pre-packaged image, run: + ``` + vagrant up --provider=virtualbox + ``` + + If you wish to use a specific version of the pre-packaged Submitty VM, on Linux/MacOS type: + ``` + PREBUILT_VERSION={version} vagrant up --provider=virtualbox + ``` + + or on Windows, type: + ``` + SET PREBUILT_VERSION={version} + vagrant up --provider=virtualbox + ``` + + *The version must be only the numbers, not including the `v` in front, for example `24.05.00.2405260215` not `v24.05.00.2405260215`* + + *This process will take 10 minutes to maybe half an hour + depending on your internet connection speed.* + + + ***Note:** The vagrant up command creates and provisions the virtual machine on the first run. + The `--provider` flag is important if you have more than one provider + installed on your machine (e.g., VirtualBox, VMWare, QEMU, libvirt). + For subsequent runs of `vagrant up` (e.g., to re-start the VM), + you do not need to append the `--provider` flag as the VM is + already created.* + + + * **Build from scratch** + + * Using QEMU on an M-Series Arm MacOS, type: + ``` + vagrant up --provider=qemu + ``` + + * On Linux or Intel-based Mac, type: + ``` + FROM_SCRATCH=1 vagrant up --provider=virtualbox + ``` + + * Or on Windows with `cmd`, type: + ``` + SET FROM_SCRATCH=1 + vagrant up --provider=virtualbox + ``` + + *As noted above, you do not need to append the `--provider` flag on + subsequent runs of `vagrant up` after the VM is already created.* + + *Building the VM from scratch will take anywhere from 30 minutes to a few hours + depending on your internet speed.* + + + ***ADDITIONAL NOTE:** When the `vagrant up` command completes + successfully, you will be able to access the Submitty website + (instructions follow in the next section). The VM will continue + to run jobs in the background and consume a nontrivial amount of + CPU resources, while completing a backlog of autograding for a + dozen or more sample submissions for each of the more than 100 + users in the sample courses.* + + + * **Build from scratch without sample submissions** + + If your development work *will not require sample assignment + submissions or autograding results*, you may prepend + `NO_SUBMISSIONS=1` to the previous command, which will skip the + creation of these sample submissions and their autograding and + decrease the time to complete installation. + + * On M-series ARM Mac: + ``` + NO_SUBMISSIONS=1 vagrant up --provider=qemu + ``` + + * On Linux or Intel-based Mac: + ``` + NO_SUBMISSIONS=1 FROM_SCRATCH=1 vagrant up --provider=virtualbox + ``` + + * On Windows using `cmd`: + ``` + SET NO_SUBMISSIONS=1 + SET FROM_SCRATCH=1 + vagrant up --provider=virtualbox + ``` + + On Windows using PowerShell, you will have to set the environment variables differently: + ```pwsh + $Env:NO_SUBMISSIONS=1 + $Env:FROM_SCRATCH=1 + vagrant up + ``` + + If you want to unset the variables later in `cmd`, you can do: + ``` + SET NO_SUBMISSIONS= + SET FROM_SCRATCH= + ``` + + Or in PowerShell: + ```pwsh + Remove-Item Env:\NO_SUBMISSIONS + Remove-Item Env:\FROM_SCRATCH + ``` + + Similarly, you can check that the variables are set in `cmd` with: + ``` + SET NO_SUBMISSIONS + SET FROM_SCRATCH + ``` + + Or in PowerShell: + ```pwsh + $Env:NO_SUBMISSIONS + $Env:FROM_SCRATCH + ``` + + +7. AND YOU ARE DONE! + + When the installation has completed, you should see the message: + ``` + ##################################################################### + + INSTALLATION SUCCESS! + + .GGQGGGSlu + .GGGGGGGGGGGS + :llUGGGGGGGGGGGGGGGG + 'GGGGGGGGGGGGGGGGGGb . + %GGGGGGGGGGGGGGG~ ..GSGGG + GGGGGGGGGGGGGGSGGGGGGGGGG[ + ;GGGGGGGGGGGGp\ \ \GGGGGGGGL + !GGGGGGGGGGGGGGS\ \ \GGGGGG + GGGGGGGGGGGGGGGGG\ \ \9GGGG + %GGGGGGGGGGGGGGGS/ / /.GGG + %GGGGGGGGGGGGGS/ / /GGG + '%NNNNNNNNNNNNNNNNNN + ##################################################################### + ``` + + ***Note:** There are times when the install will pause for a brief + period with the message `Done`. This does not mean the install has + ended, and the install should continue after a bit of time.* + + + If you do not see this message due to an error or the installation + has frozen, check out: + [Installation Troubleshooting](/developer/troubleshooting/installation_troubleshooting) + +--- + +## Using your Submitty Developer VM + + +1. When the VM is "up", you can go visit the homework submission + website. + + * From a web browser (Chrome, Firefox, IE, etc.) on your host + computer, go to: + + + + (see the VM login & password info below) + + * You can test the submission, autograding, and viewing of the + grade details by uploading sample submissions from the Submitty + repository, located in one of these directories: + + - The ["tutorial" course](https://github.com/Submitty/Tutorial/tree/main/examples) + + - The ["sample" course](https://github.com/Submitty/Submitty/tree/master/more_autograding_examples) + +2. When the VM is "up", you can connect from your host computer to the + virtual machine via ssh. Windows users will need to install SSH + software (e.g., + [WSL](https://ubuntu.com/wsl), or + [Cygwin](https://www.cygwin.com/), or + [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) ). + From a terminal in the repository directory type: + + ```sh + vagrant ssh + ``` + + You will connect to the VM as the `root` user. + + If `vagrant ssh` asks for a password for the root@127.0.0.1 user and "vagrant" without the quotation marks does not work, look at the vagrant ssh config file and make note of the hostname and port. + + ```sh + vagrant ssh-config + ``` + + Then directly ssh into the VM by + + ```sh + ssh vagrant@hostname -p port + ``` + + If it asks for password, it should be "vagrant" + and then + + ```sh + sudo su + ``` + + to login as the root user. You should then see you are logged in as root@vagrant. + +3. The following users exist on the VM: + + | user | password | role | + |------|----------|-------| + | superuser | superuser | Superuser | + | vagrant | vagrant | OS user | + | root | vagrant | OS user | + | submitty_cgi | submitty_cgi | Submitty process | + | submitty_php | submitty_php | Submitty process | + | submitty_daemon | submitty_daemon | Submitty process | + | postgres | postgres | database process | + | instructor | instructor | Instructor submitty user | + | ta | ta | Full access grader submitty user | + | grader | grader | Limited access grader submitty user | + | student | student | Student submitty user | + + Note that there are many more student and grader users on the VM; you may + log in as any of them using their **User ID** as the username and password. + The easiest way to see the list of users is to log in as an instructor, access + a course, and click **Manage Students** or **Manage Graders**. + +5. The VM has the following four courses by default and they are all part of the current semester: + + * tutorial + * sample + * development + * blank + + **Note**: The current semester is calculated by either using an `s` if in the month is < 7 else use `f` + and then take the last two digits of the current year. So April 2017 would be `s17` while September + 2017 would be `f17`.* + + +--- + +## Starting and Stopping the Submitty VM + + +1. When you take a break from Submitty development work, you can + suspend the Submitty VM to save resources (CPU and battery) on + your host machine. + + ``` + vagrant suspend + ``` + + Alternatively, you can halt the virtual machine. This is a more + complete shutdown and will take slightly longer to restart when you + resume development work. + + ``` + vagrant halt + ``` + +2. To resume work on a VM that is suspended or halted: + + ``` + vagrant up + ``` + + Note: when resuming work, you may see this warning several times, + `default: Warning: Remote connection disconnect. Retrying.. .` + These warnings are not harmful and can be ignored. + +3. If you just want to restart the VM (same as `halt` then `up`), type: + + ``` + vagrant reload + ``` + +4. Read the [Development Instructions](/developer/development_instructions) page + for instructions on updating an existing installation with recent + code changes. + +5. To completely delete the virtual machine, type: + + ``` + vagrant destroy + ``` + + And if desired (to start over from scratch with a fresh VM): + + ``` + vagrant up + ``` +--- + +## Testing with a remote device + +1. Make sure that the VM is stopped. + + ``` + vagrant halt + ``` + +2. In the `Vagrantfile`, add a new port under `config.vm.define` for the primary box below the other forwarded ports (site, websockets, database). + + ``` + ubuntu.vm.network 'forwarded_port', guest: 22, host: , id: "ssh", host_ip: "0.0.0.0" + ``` + + Replace `` with the port you want to expose externally on the machine that is running the VM, and expose the specified port on the machine if necessary. + +3. Start the vagrant machine with `vagrant up`. + +4. Retrieve the private key for the vagrant machine, located at `/.vagrant/machines///private_key`. + + At the time of writing, `` is `ubuntu-22.04`, and `` is `virtualbox`. + +5. Use SSH to connect from the remote device to the machine that is running the VM, and use SSH port forwarding (local forwarding) to forward the necessary ports. + + The username to sign in is `root` and the authentication method is with private key (using the private key specified in part 4). If you encounter authentication issues, try adding `vagrant` as the password in addition to the private key. + + For most things, you will only need to forward the `site` port and the `websockets` port (1511, 8443). + + The configuration to set up the connection will differ based on your client; below is an example for if you're using an SSH binary to connect, assuming that the SSH configuration file has the username, private key (identity file), IP address (host name), and port stored. + + ``` + ssh -L 1511:localhost:1511 -L 8443:localhost:8443 $SUBMITTY_HOST + ``` + + where `$SUBMITTY_HOST` is a reference to the `Host` from the SSH config file. + + **Note:** + Especially for mobile operating systems, make sure that your SSH client supports SSH port forwarding. On iOS, you will also have to enable location tracking for the client to keep the connection alive in the background. + + This has been tested with Blink for iOS and Termius for iOS (also available on Android, untested). + +6. Navigate to `localhost:1511` on the remote device. + +--- + +## Developing in HTTPS + +For *developers* who need to upgrade to HTTP/2 in their development environments, +please follow the step below: + +- Run `bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/dev-upgrade-h2.sh up`. + + After a successful execution, please use `https://` instead of `http://`. + +- To downgrade to HTTP/1.1, run `bash /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/dev-upgrade-h2.sh down`. + +The script should automatically handle the upgrading and issuing a self-signed +certificate. If your browser complains about the security, please head to +[WebSocket](/developer/developing_the_php_site/websocket). + +--- + +## Increasing VM Resources +If you find that the VM is running slowly, you can increase the resources allocated to it. By default the VM is allocated 2GB of RAM and 2 CPUs. You can increase these values by setting the `VM_MEMORY` and `VM_CPUS` environment variables before running `vagrant up`. For example, to allocate 4GB of RAM and 4 CPUs, you can run: + +```sh +export VM_MEMORY=4096 +export VM_CPUS=4 +vagrant up +``` +If your system has 8GB of RAM it is recommended to set `VM_MEMORY` to 4096 (4GB) and `VM_CPUS` to 2 or 4. If your system has more RAM, you can increase these values further, but be careful not to allocate too much RAM as it may cause your host system to become unresponsive. diff --git a/_docs/developer/getting_started/worker_vm.md b/_docs/developer/getting_started/worker_vm.md new file mode 100644 index 00000000..730bef5a --- /dev/null +++ b/_docs/developer/getting_started/worker_vm.md @@ -0,0 +1,181 @@ +--- +title: Worker VM Setup +category: Developer > Getting Started > Advanced Setup +redirect_from: + - /developer/worker_vm +--- + +If you are are developing or testing the distributed system for +automated grading, you may want to set up one or more *worker +machines* in addition to your primary vagrant virtual machine. + +## Automated Worker Installation + +1. First set up your main/primary machine by following the normal + [VM Install using Vagrant](/developer/getting_started/vm_install_using_vagrant) instructions. + +2. Ensure you have [Python 3](https://www.python.org/downloads/) installed on your machine, run: + ``` + python3 --version + ``` + +3. To generate configuration for a worker machine, run: + ``` + vagrant workers generate + ``` + + If instead you need multiple workers, append the `-n` flag, ex. for 3 machines: + ``` + vagrant workers generate -n 3 + ``` + + _NOTE: This will create the vagrant configuration file: `.vagrant/workers.json`._ + + +4. If you are on MacOS running QEMU, restart the network socket in public mode: + ``` + vagrant workers socket restart --public + ``` + _NOTE: Using the `--public` flag will make your worker VMs accessible to anyone + on your local network, which may be a modest security concern. + We suggest this to minimize possibility of errors while creating the + worker machines and will revert this in a later step._ + + _NOTE: Running a socket command while a worker machine is running can detach the + process, making the VM inaccessible to vagrant. If this happens and you are unable + to `vagrant workers halt`, then you may run `pkill -15 -f qemu-system-` to kill + all virtual machines running on your computer (including the main Submitty VM)._ + +6. Now you can create the worker machine(s) with: + ``` + vagrant workers up + ``` + _NOTE: Do not use the --provider flag with this command, since it will conflict with the + provider of the main virtual machine._ + + When this is finished, you should see the Submitty duck ASCII art for each new worker machine. + +7. You can verify that all the worker machines are running with: + ``` + vagrant workers status + ``` + +8. `vagrant ssh` into the main virtual machine and run: + ``` + refresh_vagrant_workers # (runs python3 /usr/local/submitty/GIT_CHECKOUT/Submitty/.setup/bin/refresh_vagrant_workers.py) + submitty_install + ``` + +9. To stop the worker machines, you can run: + ``` + vagrant workers halt + vagrant workers socket stop + ``` + + _For MacOS QEMU users: Once the virtual machine(s) are halted, if you would like to restart under + private networking, you may do so by omitting the `--public` flag from the `vagrant workers socket start` command._ + + +--- + +## Connecting to the Worker Machine + +If you would like to ensure the worker is functioning properly, or enter the worker machine for managing it directly, you can follow these steps. + +To connect to a worker machine through SSH, run: +``` +vagrant workers ssh +``` + +If you want to test the connection between the primary VM and a worker, you can first `vagrant ssh` into the primary machine and then run this command to SSH into the worker from there: +``` +su submitty_daemon -c ssh +``` + +The list of worker names can be displayed with `vagrant workers status`. + +__NOTE__: Depending on the performance of your computer and the size of the autograding queue passed to the worker, the SSH command may hang for some time. + +--- + +## Manual Worker Installation (VirtualBox) + +1. Open the Virtual Box application. + +2. Click `New` to create a new machine. + Give it a useful name: e.g., `worker_machine_a` + Specify the type: `Linux` + And the version: `Ubuntu 64` + +3. Specify the amount of memory: 2048 = 2GB should be sufficient. + +4. Create the disk as a `new virtual disk`. + Specify RAM memory: 2048 (2GB) + Create new virtual disk. + Choose `VDI` + Choose `Dynamically allocated` + Specify size: e.g., 20GB + +5. Download the Ubuntu 22.04 installer 64 bit .iso. + Save this somewhere on your host computer. + +6. Click on `Start` to power on. + Browse your files to find the Ubuntu installer .iso we downloaded earlier. + Press `Start`. + +7. Follow the Ubuntu installation menu... + Click `Install Ubuntu`. + Select `English` keyboard. + Select `normal` installation. + Agree to `Erase disk & Install Ubuntu`. + Specify your timezone. + Then specify your username, computer name, password. + Then click through various menus, and wait a while installing system. + Then restart the VM to finish installation. + +8. At some point, it will suggest that you install updates for Ubuntu 22.04, go ahead and do that. + You'll probably have to reboot. + +9. Allow ssh connections to the worker VM from outside (e.g., from your primary machine): + from virtual box, select the VM, click on `Settings`, then `Network`, + `Enable Network Adapter` should be checked, then set + Attached to: `Bridged Adapter` + +10. From the VM, open a terminal and install a bunch of additional packages: + + ``` + sudo apt update + sudo apt install net-tools + sudo apt install openssh-server + sudo apt install git + ``` + +11. Install Guest Additions (Improves screen resolution, copy paste to/from the VM, etc.) + + While the VM is running, focus on the VM window. + Then from the menu, select `Devices` -> `Insert guest additions CD image` + Open a terminal in the VM + Go to the guest additions CD directory, and run the guest additions installer: + + ``` + mount + cd /media//VBox_GAs_/ + sudo ./VBoxLinuxAdditions.run + ``` + +12. Get a permanent IP address for your machine + Go to your router, assign a fix ip address for your mac address + E.g., in a browser, go to `192.168.0.1` and log in... + Helpful command to find your mac address & current IP address: + + ``` + ifconfig + ``` + +13. Prevent worker VM from going to sleep (so you can send autograding jobs to it at any time). + `Settings` -> `privacy` -> `screen lock` -> `turn off screen lock` + `Settings` -> `power` -> `suspend & power button` -> `automatic suspend` == off + `Settings` -> `power` -> `blank screen` == `never` + +14. Follow the [worker installation instructions](/sysadmin/worker_installation) + diff --git a/_docs/developer/getting_started/xdebug.md b/_docs/developer/getting_started/xdebug.md new file mode 100644 index 00000000..549c6875 --- /dev/null +++ b/_docs/developer/getting_started/xdebug.md @@ -0,0 +1,55 @@ +--- +title: Xdebug Setup Instructions +category: Developer > Getting Started > Advanced Setup +redirect_from: + - /developer/xdebug +--- + +Xdebug is a PHP extension automatically enabled in the Vagrant VM that allows for step-by-step code debugging, code profiling, and code tracing. For more information about the features of Xdebug, see [xdebug.org](https://xdebug.org/). + +For the default configuration, it is recommended to use an extension to enable one of the Xdebug modes; see [https://www.jetbrains.com/help/phpstorm/browser-debugging-extensions.html](https://www.jetbrains.com/help/phpstorm/browser-debugging-extensions.html) for a list of extensions that can be used with Xdebug. When using one of the `Xdebug Helper` extensions, the specified mode should be selected while on a page (Debug/Profile/Trace) from your local Submitty installation to use it. + +### Debug + +#### PhpStorm + +See [PhpStorm Setup Instructions#Enable PHP Debugging using xdebug](/developer/getting_started/phpstorm#enable-php-debugging-using-xdebug) for details on how to enable and use Xdebug in PhpStorm. + +#### VSCode + +In order to use debug mode with Xdebug, the [Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension or equivalent extension may need to be used to connect directly into the Vagrant machine. Additionally, the [PHP Debug](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) extension should be installed. + +Create a file titled `launch.json` under the `.vscode` folder in the root of the currently opened folder, creating the `.vscode` folder if it does not exist, and paste the following into the file: + +``` +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9000, + "pathMappings": { + "/usr/local/submitty": "/usr/local/submitty/GIT_CHECKOUT/Submitty" + } + } + ] +} +``` + +After this, Xdebug can be started by going to the `Run and Debug` tab (play button with a bug on the sidebar), selecting `Listen for Xdebug` in the dropdown menu and clicking the play button. A short bar will appear that lets you control and end the debug session. To create breakpoints, click to the left of the line numbers; inline breakpoints can be created by right clicking and selecting `Add Inline Breakpoint`. + +### Profile + +After visiting a webpage with the profiling flag enabled, profiler results will be stored by default under `/.vagrant/Ubuntu/profiler`, under files that are titled `cachegrind.out.`. These files can be analyzed using PhpStorm's built in tools or using a tool such as KCacheGrind/QCacheGrind. + +Note: It is recommended to only enable profiling when needed as profiling increases load times and the files generated take up a significant amount of space. + +#### PhpStorm + +Follow the steps under Debug to enable debugging with PhpStorm, and then follow [https://www.jetbrains.com/help/phpstorm/profiling-with-xdebug.html#snapshotLocation](https://www.jetbrains.com/help/phpstorm/profiling-with-xdebug.html#snapshotLocation), starting at `Specify the location for storing accumulated profiling data`. + +#### General + +To view the profiled files in a visual format, programs such as KCacheGrind/QCacheGrind can be used - a Windows binary is available here: [https://sourceforge.net/projects/qcachegrindwin/](https://sourceforge.net/projects/qcachegrindwin/), and macOS/Linux users can use [Homebrew](https://brew.sh/) to install it with `brew install qcachegrind`. diff --git a/_docs/developer/google_summer_of_code/2018_GaganKumar.md b/_docs/developer/google_summer_of_code/2018_GaganKumar.md new file mode 100644 index 00000000..4b693de6 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2018_GaganKumar.md @@ -0,0 +1,138 @@ +--- +title: Gagan Kumar +category: Developer > Google Summer of Code 2018 +redirect_from: + - /developer/GSOC2018_GaganKumar + - /developer/2018_GaganKumar +--- + +# Discussion Forum Enhancements + +### [Submitty](http://submitty.org) +*Homework Submission, Automated Grading, and TA grading system* + +GitHub : [https://github.com/Submitty/Submitty](https://github.com/Submitty/Submitty) + +#### Google Summer of Code 2018 with Submitty + +Worked with Submitty on Discussion Forum under Google Summer of Code 2018. *Barbara Cutler*, *Master_Odin* and *Andrew Aikens* were officially assigned mentors who along with other Submitty members helped me at various stages such as design problems, code review and performance issues which made this journey easier for me. + +#### What I learned + +I got hands-on experience using twig templates along with PHP giving high code reusability and secure code. Using E2E tests reduces a lot of time as compared to testing applications manually. I got exposed to writing complex SQL queries. + +This project helped to inculcate a spirit of teamwork in me and instilled the coordination, cooperation and management required to work in a team. + +I also absorbed the importance of code reviews/feedbacks by others as they might have a completely different angle to view the problem. + +#### [Discussion Forum](/instructor/forum) + +Submitty has a student-faculty portal named **Discussion Forum**. It can be used for asking queries, announcements, notes sharing, etc. + +###### Contribution + + [29 commits](https://github.com/Submitty/Submitty/commits?author=scopeInfinity) ![Commits](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGUAAAAOCAYAAAA2T9JWAAAABHNCSVQICAgIfAhkiAAAABl0RVh0U29mdHdhcmUAZ25vbWUtc2NyZWVuc2hvdO8Dvz4AAATHSURBVFiF7ZhfTFN3FMc//Gnv1U5bjIO6gFSc2Gz+weAiJMtkCdkakoU+zIWEzHV7cCwhsQ9LZraYdJpoX7aZqLHxYeuSaVz2MDIzLZlmxS1SHlSmzBRQrMCkVQcFqdwW2t8eECh/LhbQ6RY/yX0493zP6bf39PzS3DQhhOAZTxXpT9rAM6ajMpQQriYrhkuNqoVK+BRV56yYWi5PTkQaqGl6H+MZK8bfd3Ogd3BabXNbLbL3EL6FOJ8j8ebv6DKv55pd/Tup67r4u6yQVnniajN9SuRBdsTjpNO8mTbDZq5bnNwLLszrjEMJdh3CNaRTr+o9SlnLFUxLcqYkQrhajhLI3k2gvI7mwizcLW688SRJpA57MILxYc6GO/D0huaem4GEz0lnzSU0Rbnz1A0QD79EVnMba5XRqzCwDx1AuJ6eGh9a91kKw2dZUeQjZK9nJGV305k+lGgD9ptadq0yI6tVLSrHveUTbDrNlNoL1EU2YF9ZgAwYs7dh0zRyom9MEMJ19Qzm1RWYH3ZwDjXguOFHmWtuBtKNb7PC+wWGImmeuihxRSJjhgcS955EMVezvEQP6Fm8qxqt9yT3UzU3k4/J4SCe1uMo+bVYtbNULSrArJnhfqSDgDYbU8bYjRxM8jCBodGpBP86hEuqxrl8li18HJheRFb9haWiGyARvsOg3co143razdvpqesiAQz7u0kzryZzTGpYjcbQTTQwf7uZyYFy140jWsmJvCzknnl0S8RQMnKTNkyLnKFBGYmNbuANLY5XSjFwSrWF53I1VbdHT+v+BBjPfAXpBTg2f4k5oJ6zL52H35R5nkXWEuLWj1hWl0fC8zndto/pK/qexeEoaXLyZkmkyVHiC9iUiaHE/TjaO6jaUItpvt3StcjxvqRjJYYSH0bOBE/rDyj5e7FKQFS9hWXDMcIAA99Q0l6At3jrxJBnyz1WXmaZa994lGGxk1X0KgPefnRGCREYSNJGEYpE5hRjUdd2Oh1XAdA6fsTIZ5Pi/Jq8ce3EUO6dwxPpJtj0Dk6ARIxQ4gKmJhueLVbMqXjXFWCKXcEfB3MGQAh/RIc5v5u669347n6IsR0gRngELN4+XKW7qZr9qH/yKLcZ8kfRFuUxejJHSQDIoDXlIjzdjPDgYQavEwvnojNNbiHZDrLKGgUk0gx6MpgcJzMxFMMOmst3TGR69mIMlhPYVApAsLcBX3oxVsNz6ualUqqWHONAZweWVQWEe47jThTj1hdTUlaHa0wXPYWlqQPHa7WUzPUBPWKGvT8xZNjK0iK9uijcwB3L12jc35JjySbhPUJ/8yb0ZXrS5bdYbD/CXd8bGEsg4jzGsMWObuoKy3oyJ/3lnBonIdS4tUfkXDw/Hp6+uE1sbO0UQgjR+KdNSPUVQqqvENRXCKm+UuRf+WNUeP+82OmziZxfKkXOb3vEkb7o9N7Kz+LNhoOiUfXDHy2Rna+LVmmN8LNS+Fkj/NIa0b7zvIgLIfrfWyc69rc/VBc7vV/cXFssWvXrRNvGd0XP6dB4/+FfDz/IFYtrlYfFYN/C/KYJkeJrlvBRau5tw5WXlZL8P4PPyS3/B7xgy37STsZJ+TVLMLEeW/b/bCDAiLIJg/XpGQhA6pvyjH+NfwDdsfknHa9eEQAAAABJRU5ErkJggg==) + + +- Paging on Thread List + + - Bidirectional scroll for thread list ([#2654](https://github.com/Submitty/Submitty/pull/2654)) + + - Thread list paging ([#2473](https://github.com/Submitty/Submitty/pull/2473)) + + Forum page has thread list in the left column. However, as the semester grows, the number of threads can dramatically increase the page loading time. Introducing paging in thread list not only decreases the page loading time but it also enhances the user experience by loading limited threads in a view at a time. + +- Merge Common Threads + - Forum: Show Merged threads ([#2599](https://github.com/Submitty/Submitty/pull/2599)) + - Merge common threads ([#1962](https://github.com/Submitty/Submitty/pull/1962)) + + A lot of times, students create different threads on the same context, thus increasing confusion. Now, the instructor can club similar context threads with just a few clicks. + +- Notifications ([#2591](https://github.com/Submitty/Submitty/pull/2591)) + + Notifications are needed so that the user is kept updated about the associated events. Submitty, now supports notifications which get triggered when - + + - There’s a new announcement, + - Someone replies to your posts, + - Instructor edits your posts, + - Instructor merges your thread into another thread. + + Currently, notification is triggered only on forum related events. However, the same architecture is compatible to handle notifications from different components of Submitty. + +- Thread Status ([#2341](https://github.com/Submitty/Submitty/pull/2341)) + + The thread can be created with the intention of asking a question waiting for some response or it can be simply a comment. Thus thread status can be one of **Comment**, **Unresolved** or **Resolved**. Threads are visually marked on the thread list and can also be filtered on the basis of their thread status. + + Instructor or the author of the thread is free to switch between thread status and can mark the thread as resolved along with the problem. + +- Allow students to pin threads ([#1973](https://github.com/Submitty/Submitty/pull/1973)) + + It's possible that there are a few threads which students want to watch closely. Thus, each student can pin the threads of their interest and move them to top in their thread list. + +- Posts/Threads related + + The code responsible for thread creation form, posts reply form and edit posts/thread form now shares a common twig template. + + - Allow the original author to edit post/thread ([#2301](https://github.com/Submitty/Submitty/pull/2301)) + + Initially, only the instructor was allowed to edit posts/threads because of a few concerns. Now even students are allowed to edit their own posts apart from just instructors. Along with it, the instructor has the power to obtain the list of edit history containing the changes with the timestamp and the information of the user who modified it. + + - Show deleted threads ([#2151](https://github.com/Submitty/Submitty/pull/2151)) + + Instructors are authorized to delete any posts/threads at any point of time. But in some cases, we want the instructors to be able to view all posts/threads irrespective of their deletion status. Thus instructors can toggle _Show Deleted Threads_ button to make use of this functionality. + + - Recover posts/thread ([#2248](https://github.com/Submitty/Submitty/pull/2248)) + + It's possible that after some time, the instructor wants to recover a post/thread. He can do the same easily just by clicking the undelete button attached to any post. + + - Multiple Attachments ([#2243](https://github.com/Submitty/Submitty/pull/2243)) + + Allowing a user to dynamically add/remove multiple attachments either one by one or multiple at once while creating a thread or replying to a post. Also visually show the attached image as a thumbnail to avoid the mistake of attaching the wrong file. + + - Edit Thread ([#2150](https://github.com/Submitty/Submitty/pull/2150)) + + Thread-specific information like thread title and categories are editable. + +- Visually marked thread with my posts ([#2585](https://github.com/Submitty/Submitty/pull/2585)) + + Threads containing at least one of the current user’s posts are marked visually in the thread list. + +- Thread Categories + + - Allow multiple categories for a thread ([#2083](https://github.com/Submitty/Submitty/pull/2083)) + + Earlier, all the threads were assigned to one category of relevance. + + However, now each thread is allowed to have more than one category and anyone can filter the threads based on a set of categories. + + - Edit Categories (Reordering) ([#2126](https://github.com/Submitty/Submitty/pull/2126)) + + - Categories having colors and edit category features ([#2135](https://github.com/Submitty/Submitty/pull/2135)) + + The instructor is allowed to add/remove a category and even category name. In addition, categories are now ordered. And the same order will be used in thread creation page, edit thread form and filter thread based on categories. + +- Selenium E2E Tests for the forum + + Worked on basic end to end selenium tests for the discussion forum. [(test_forum.py)](https://github.com/Submitty/Submitty/blob/master/tests/e2e/test_forum.py) + +- Refactoring DB Queries + + Used a single helper function to generate a single complex SQL query required to obtain the list of threads along with other desired information. This also minimises the PHP to SQL calls. The same function can be used by different methods to obtain an SQL query needed to fetch information without re-writing the whole query. + +##### Enhancements or Bug Fixes + +- Added more sample thread/posts for forum ([#2009](https://github.com/Submitty/Submitty/pull/2009)) + +- Reply Box Enhancements ([#2219](https://github.com/Submitty/Submitty/pull/2219)) + +- Fixed inclusion of Sortable JS twice ([#2375](https://github.com/Submitty/Submitty/pull/2375)) + +- Bug Fix for show deleted thread ([#2270](https://github.com/Submitty/Submitty/pull/2270)) + +- Handle Dangling Posts on Creation ([#2229](https://github.com/Submitty/Submitty/pull/2229)) + +- Show author email address ([#2527](https://github.com/Submitty/Submitty/pull/2527)) + +- mailto icon on all post ([#2609](https://github.com/Submitty/Submitty/pull/2609)) + + diff --git a/_docs/developer/google_summer_of_code/2018_TusharGurjar.md b/_docs/developer/google_summer_of_code/2018_TusharGurjar.md new file mode 100644 index 00000000..71fa7b8d --- /dev/null +++ b/_docs/developer/google_summer_of_code/2018_TusharGurjar.md @@ -0,0 +1,139 @@ +--- +title: Tushar Gurjar +category: Developer > Google Summer of Code 2018 +redirect_from: + - /developer/GSOC2018_TusharGurjar + - /developer/2018_TusharGurjar +--- + +# Instructor Interface for Plagiarism Detection + +[Submitty](http://submitty.org) is an open source programming +assignment submission system from the +[Rensselaer Center for Open Source Software (RCOS)](https://rcos.io/), +launched by the +[Department of Computer Science](http://www.cs.rpi.edu/) at +[Rensselaer Polytechnic Institute](http://www.rpi.edu/). + +My GSoC project involved working on the Plagiarism Detector (also called "Lichen") of Submitty Organization. +Along with my GSoC project, I also worked on implementing some crucial features and fixing bugs. +Working on various features and bugs throughout Submitty helped me learn even more about Software Development. + +Throughout my GSoC journey, I learnt about Working of Plagiarism Detector, Web Technologies, Servers, Travis Testing. + + + + + +### Tasks done as part of my GSoC project + +1. **Made Java, Python, C++ tokenizer for the core plagiarism module.** + + Initially I was assigned to make tokenizers using Microsoft Language Servers. + Microsoft Language Servers are used by various text editors like Sublime, Atom, etc and it provide the text editor with the features like AutoComplete Suggestion, References, etc. We aimed at sending a file and getting its tokens from the server, but due to no direct client request method for tokens, couldn't integrate Microsoft Language Server. + So finally made tokenizers similar to how language server do tokenization internally. This involved exploring codebase of [Cquery language server](https://github.com/cquery-project/cquery), [Palantir Language Server](https://github.com/palantir/python-language-server), and [Java Language Server](https://github.com/georgewfraser/vscode-javac). + + **Link to commits (merged)**- + + + [Python and CPP tokenizers (#3)](https://github.com/Submitty/Lichen/commit/00348500a1fbd01f6a14d54d399f6e8f73034e9b) + + [Java tokenizers (#8)](https://github.com/Submitty/Lichen/commit/5dbf12720fcc41315e396ea4121bb52d3ea13e7f) + +2. **Worked on Visualization tools for Plagiarism Interface** + + Work on the new interface of Plagiarism Detector to let instructor see plagiarism results on the interface. Worked on visualization tool to make plagiarism result more intuitive to differentiate between plagiarism vs. coincidental matching. + + Implement various visualization tools like- + + There can be different kind of matches like common code, suspicious, match with instructor provided code. + + a) Used colors in code boxes where code is is displayed to differentiate between various type of matches. Also add various color click events to display with whom that colored section matches with. + + ![](/images/lichen_interface.png) + + ![](/images/lichen_color_click.png) + + **Link to commits (merged)**- + + [Lichen first draft (#2239)](https://github.com/Submitty/Submitty/commit/2b6d91b0ac34df21d2991cb935656c90bb5cd9d7) + + [Lichen color click events (#2343)](https://github.com/Submitty/Submitty/commit/e90f935fa3fe082e762323ed569ccb915f9d7391) + + [Lichen minor modifications (#2592)](https://github.com/Submitty/Submitty/commit/b46f35a7a55f4c1636dc3e6981328d2bd440d764) + + [Lichen main page modifications (#2626)](https://github.com/Submitty/Submitty/commit/c75ade7210fc4e7794892c19417edc031f74259e) + + +3. **Implemented backend for New Plagiarism Detector** + + **Link to commits (merged)**- + + [Lichen first draft (#2239)](https://github.com/Submitty/Submitty/commit/2b6d91b0ac34df21d2991cb935656c90bb5cd9d7) + +4. **Automated the new Plagiarism Interface by integrating to Submitty Daemon** + + Automated the plagiarism detector to do various jobs from interface itself. This includes creating configuration file for gradeable for which the plagiarism is to be run, editing configuration, rerunning plagiarism detector for a gradeable, delete plagiarism results for a gradeable. + + **Link to commits (merged)**- + + [Run lichen plagiarism as submitty daemon job (#2423)](https://github.com/Submitty/Submitty/commit/fe7128093e69b809e53b93ae97c33dbee8c14612) + + +### Ongoing task + +1. **Initial Test Suite for Plagiarism Detector (no pull request yet)** + + + I am currently working on testing and debugging of Plagiarism Detector. This involves creating regression test for plagiarism detector. This Regression test will check whether the tokenization, hashing of token sequence and matching of hashes is done correctly. This regression test then will be integrated to travis. + + + +### New Features implemented and Bug fixed along with GSoC Project + +1. **Extended Registration section from numeric to alphanumeric** + + **Link to commits (merged)-** + + [Alphanumeric registration section (#2069)](https://github.com/Submitty/Submitty/commit/3423da9ff01f7ff2f82c237d144b22a1d84b076f) + +2. **Implemented Delete Gradeable Feature** + + This feature can be used instructor to delete a gradeable provided some constraints are matched. + + **Link to commits (merged)-** + + [Delete gradeable feature (#2031)](https://github.com/Submitty/Submitty/commit/09a2c9247980238763d3e3d71d46fe3796d9068a) + +3. **Implemented Team Export & Import Feature from one gradeable to other** + + This feature help instructor transport the teams from one gradeable to another. This can be used in cases where instructor wants same teams across many gradeables in course. + + **Link to commits (merged)-** + + [Team member export and import feature (#1982)](https://github.com/Submitty/Submitty/commit/deafde544c23725880eb2a36887f4a8a812af518) + +4. **Implemented Rebuild Assignment feature** + + This feature allows instructor to rebuild a gradeable from interface itself rather than going to server and running rebuild script there. + + **Link to commits (merged)-** + + [Assignments can be rebuild from interface (#2105)](https://github.com/Submitty/Submitty/commit/33e60f59905e4f12888663448ad3411f7fc5a4f7) + +### Commit History (including all commits which got merged) + + +[Commits in Submitty/Submitty repo](https://github.com/Submitty/Submitty/commits?author=tushargr) + +[Commits in Submitty/Lichen repo](https://github.com/Submitty/Lichen/commits?author=tushargr) + + +### Building the project + +For building the project, it will require to build complete Submitty System. + +1. Instructions for building Submitty- [Developer/VM Install using Vagrant](/developer/vm_install_using_vagrant) + +2. For using Submitty and its Plagiarism Detector, follow instructions at [Developer/Installation](/developer/vm_install_using_vagrant) and [Instructor/Plagiarism Detection](/instructor/plagiarism) + diff --git a/_docs/developer/google_summer_of_code/2019_AnubhavSingh.md b/_docs/developer/google_summer_of_code/2019_AnubhavSingh.md new file mode 100644 index 00000000..fed1ccb4 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2019_AnubhavSingh.md @@ -0,0 +1,107 @@ +--- +title: Anubhav Singh +category: Developer > Google Summer of Code 2019 +--- + +# Discussion Forum Refactor, VPAT & WebSocket Integration + +The project was an upgrade to the Discussion Forum module of the Submitty web application. The Discussion Forum allows students in a course to discuss their coursework, allowing image upload, links and code embed. My work over the summer made the Discussion Forum more user friendly in terms of accessibility and speed of using the Forum + +I am [Anubhav Singh](https://github.com/xprilion), an undergraduate student from [NSEC](https://nsec.ac.in), [Kolkata](https://en.wikipedia.org/wiki/Kolkata), as part of [Google Summer of Code](https://summerofcode.withgoogle.com/). + +This project was mentored by - [Barb Cutler](https://github.com/bmcutler), [Andrew Aikens](https://github.com/andrewaikens87) and [Shail](https://github.com/shailpatels). The project had constant guidance from [Matt Peveler +](https://github.com/MasterOdin). + +## Contributions + +[33 commits](https://github.com/Submitty/Submitty/commits?author=xprilion) ![Commits](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH4AAAAPCAMAAAAVg4veAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAkUExURf///9VHUt7y4+J+hXHGhfro6ZTUo1a8brjjwvPN0O2tsj2yWdylaL4AAAHGSURBVDjLzVXRcgIxCLyQQEjy///bhZCo56nTjg9lpnaJmoVlOY/jPwTRDenEpGfwIbg33klbSQBuFnz9TR1lsddahwDICKB2op/Jc0L0nWRP5mk7OKUJLnuvm75UQjGKP2EWAKpCJOVZJ3osqafOIONIQGRJTo1byqDPjLiuXEqJ+8n7RKYSmVTjo7vPLsXKI31ftIcxm+xI/BR18NLlSvpKi14HufAUmaIUEtHjmV7K80393P0qBvQwwQvp5Vj0k9iLIBW8cdQKadwErjwKxYsByEInS5rMizHvSWMseMci86X0xyV9qU5veMkhcCEsWTagE3vc33LuOWrp04KduccJuw3CC2rDvRSfTfxatiWse5ZiPTMAuudH5Xd3rntLc/C3qcc4uq2I6WHVlGGbNWYjQV/D4OAu9Y7+jfVml7F3frHbLccI+I7engHM8RggVdVa1XfKfOAvLgBhH70gHfTJem3vPG/n970K/p+3Nc7h4hu1DsFcrY4KAFZYQGRc7f2j7zBqi+buxxw6JGZO89SAHbRXu+fr7g+5UsQ3Xe7B50duzkFv627eAykcN8NRyu3tDSrf+PngzH/7otA36Fv/xYd/AEwUDSaVo1GeAAAAAElFTkSuQmCC) + +#### 1. Forum Refactor Templates + +In this task, I was responsible for utilising the Twig template engine all over the Forum, in sync with the rest of Submitty code. + +- [#3768](https://github.com/Submitty/Submitty/pull/3768) ForumThreadView - CreateThread and SearchResult refactor to use Twig +- [#3771](https://github.com/Submitty/Submitty/pull/3771) Forum displayThreadList use Twig +- [#3774](https://github.com/Submitty/Submitty/pull/3774) CreatePost and GeneratePostList use Twig engine +- [#3807](https://github.com/Submitty/Submitty/pull/3807) Stats page uses Twig +- [#3870](https://github.com/Submitty/Submitty/pull/3870) ShowForumThread uses Twig + +Besides bringing in the Twig template engine, I also separated out the Forum specific CSS and JS from the other files, and moved all (nearly) inline CSS and JS to separate files. + +- [#3905](https://github.com/Submitty/Submitty/pull/3905) Inline CSS and JS shift to external files + +During working on the above task, I got into discussion with Barb and Andrew about using Markdown on the Forum posts. It was decided to replace the previous formatting system for the posts and I introduced Markdown rendering for posts in [#3774](https://github.com/Submitty/Submitty/pull/3774). However, we soon ran into alerts from several users who were suddenly having their posts rendered as Markdown. Hence we came up with the following change - + +- [#4149](https://github.com/Submitty/Submitty/pull/4149) Choice of plaintext vs markdown for post + + +#### 2. Solving VPAT issues + +A very exciting part of working on Submitty for me was to discover the depth of making websites accessible. Working on the VPAT introduced me to tools I had not known to exist such as the WAVE and ChromeVox (don't install it during a meeting). I made the following commits for the VPAT issues - + +- [#3859](https://github.com/Submitty/Submitty/pull/3859) Sequential Forum Tabs Navigation +- [#4129](https://github.com/Submitty/Submitty/pull/4129) Missing label warnings in WAVE + +Some of the fixes to VPAT were covered in [#3905](https://github.com/Submitty/Submitty/pull/3905). + +#### 3. AJAXify Forum & WebSocket Integration + +Probably one of the most exciting part of my GSoC proposal for Submitty, and one task I absolutely loved working. AJAXifying the Forum fell into place slowly and steadily. It was for a simple and sort of old issue that I first worked on bringing in AJAX - + +- [#4019](https://github.com/Submitty/Submitty/pull/4019) Maintain Forum thread list scroll state + +This made the Forum threads navigation much faster, and lightweight now that we were no longer loading the entire page for every change in thread, hence it became possible to quickly click around on thread list and view all the interesting ones. + +The next step came in the form of - + +- [#4082](https://github.com/Submitty/Submitty/pull/4082) Show applied filters in Forum bar + +In this task, instead of just showing the applied Filters in the Forum bar, we went a step ahead and removed the Filter pop-up entirely, and created a sub-bar in the Forum which gets active only when any Filter has been applied. The motivation was to replicate the filter systems used in shopping websites like Amazon! + +The above changes made it very desirable to have an entire no-reloads experience of the Forum, which would allow for real-time fetching of updates to the threads (and possibly pave way for push notifications). Late in July, when Barb and Andrew asked me to work on something which I was interested in, I came up with a few ideas and it was decided to introduce a WebSocket to the Discussion Forum! + +- [#4329](https://github.com/Submitty/Submitty/pull/4329) Create Socket Server script and Push threads/posts to users + +The above PR when merged would enable a WebSocket server on Submitty (not limited to Forum, course-wide available). This socket server would allow real-time updates and notifications to be pushed to the users. I am expecting a large benefit that can be drawn from having a WebSocket push server in future for Submitty. + +#### 4. Miscellaneous + +Apart from the above three major parts, I solved a few bugs here and there. the one bug I found most interesting and typical to solve was - + +- [#4250](https://github.com/Submitty/Submitty/pull/4250) JSON display thread posts javascript fail + +What was interesting about this bug was that it was about failing to display an error message when there was an error. The bug was evasive and it took a nearly a week to figure out how to replicate it reliably. Solving this bug was more of a help to the developers on the Forum than to the regular user. + + +I was also found complaining about the Hide/Show Replies feature on the Forum which resulted in - + +- [#4360](https://github.com/Submitty/Submitty/pull/4360) Remove HidePosts feature in Forum + + +And the sad side of it all, I could not get the following completed despite spending a good couple of days on it and reading up so much about JavaScript time that I gallantly preached about it to my juniors at college - + +- [#3508](https://github.com/Submitty/Submitty/pull/3508) Show current system time on submission page + +Alas, the students will keep making excuses about different Timezones. + +Working with e2e tests using Selenium was new to me, and with continuous support from Andrew I was able to learn about it enough to update the tests as I made changes to the way the Forum was interacted with. + +## Future Scope of Work + +I believe my work on the WebSocket opens up new avenues for not just the Discussion Forum but also for the rest of Submitty. It allows the possibility of making a lot of existing features use the benefit of real time and to make new features which take benefit of it. I would look forward to seeing the following in Submitty in future - + +- Forum Search working as an extended filter, generating results on the same page instead of going to a new page. +- Push Notifications to users +- Create thread working via AJAX +- History of Post Attachments on Forum +- Sem-wide Push Notifications (currently Course-wide) +- Reflect updates to Forum Posts/Threads via WebSockets +- A Lite interface for Submitty using the [API](https://api.submitty.org/) built by [Han](/developer/google_summer_of_code/2019_XiaoHan) + +## Acknowledgments + +I had an enriching and exciting summer of 2019, working on Submitty under the [Google Summer of Code](https://summerofcode.withgoogle.com/) program. I was glad to be mentored by Barb, Andrew (thanks for going through all my PRs!) and Shail (who was an important source of issues regarding the Forum throughout). I express my sincere thanks to all students who worked on Submitty as part of RCOS, and my peers working as part of GSoC. + +I extended gratitude to [Saketh](https://github.com/sak6lab), Han and [Drumil](https://github.com/drumilpatel2000) whose comments/reviews helped me in a number of my PRs. + +GSoC with Submitty was a warm and unforgettable experience for me. Every time I talk of Open Source, Submitty will be remembered fondly. \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/2019_DrumilPatel.md b/_docs/developer/google_summer_of_code/2019_DrumilPatel.md new file mode 100644 index 00000000..8429279a --- /dev/null +++ b/_docs/developer/google_summer_of_code/2019_DrumilPatel.md @@ -0,0 +1,97 @@ +--- +title: Drumil Patel +category: Developer > Google Summer of Code 2019 +--- + +# Automating Configuration For Assignments Uploads + + Automating Configuration For Assignments Uploads is an upgrade to old assignment configuration. Previously all inputs and outputs file was to be provided at time of configuration of assignment this made input and output constant for every submission. +After this project we can add random inputs and corresponding output at the time of submission.This is possible by providing an instructor solution and python script which can generate random inputs. We can also generate only outputs from predefined inputs at the time of building gradeable. This can be used to remove dependencies on predefined output. + +I am [Drumil Patel](https://github.com/drumilpatel2000) an undergraduate Electrical Engineer from [Indian Institute of Technology, Roorkee](https://www.iitr.ac.in). + +This project was mentored by [Barbara Cutler](https://github.com/bmcutler), [Evan Maicus](https://github.com/emaicus). + +## Contributions +[34 Commits](https://github.com/Submitty/Submitty/commits?author=drumilpatel2000) + +I contributed in various part of Submitty varying from discussion forum to Automating configuration. + +#### 1. Automating Configuration + +This was my main project with which I integrated random inputs and outputs for assignment. + +- [[Feature:Autograding] solution to generate expected output ](https://github.com/Submitty/Submitty/pull/4335) + * This PR added feature to generate output for non random inputs at time of building gradeable. This decreases time of grading as output are generated before time of grading. +- [[BUGFIX:Tests] Validate solution_containers in complete_config json](https://github.com/Submitty/Submitty/pull/4280) + * PR [4151](https://github.com/Submitty/Submitty/pull/4151) broke some testcases this PR retain all testcases +- [[Feature:Autograding] Randomized input and generated output](https://github.com/Submitty/Submitty/pull/3882) + * This was main PR which is responsible for randomized input and output. Randomized input can be generated by providing Python script which will randomized input and save it in random_input. Then after randomized output was generated using instructor_solution provided by instructor at time of configuration of assignments. +- [new test_ouput and solution folder in TMP_WORK](https://github.com/Submitty/Submitty/pull/3744) + + * This PR was a refactor to old design of assignment infrastructure. Previously test_output was at root level. This added two new folders solution and test_output. Solution folder consist of solution provided by instructor which help in generation of output from inputs(both random and test input) + +#### 2. VPAT Issues + +I solved many VPAT issues in beginning of my contribution period. This help me to recognize importance and different aspect of Accessibility. I want to thank [Peter Bailie](https://github.com/pbailie) for helping and reviewing my PRs on VPAT issues. This are my PRs on some VPAT issues :- + +- [[Bugfix] Fix deleted posts not having gray background](https://github.com/Submitty/Submitty/pull/3612) +- [Resubmit "[VPAT] html tables are commented and data tables are given th…](https://github.com/Submitty/Submitty/pull/3529) +- [[Bugfix] VPAT -- Javascript Jump menu alert ](https://github.com/Submitty/Submitty/pull/3930) +- [Customizable theme using layout tables](https://github.com/Submitty/Submitty/pull/3336) +- [Radio Button Grouping](https://github.com/Submitty/Submitty/pull/3328) +- [Contrast Error in Global footer view](https://github.com/Submitty/Submitty/pull/3322) +- [Remove redundant link in sidebar](https://github.com/Submitty/Submitty/pull/3321) +- [Change contrast and remove inline css in navigation button](https://github.com/Submitty/Submitty/pull/3296) + +#### 3. Grade Override + +This series of PRs was meant to solve [#2982](https://github.com/Submitty/Submitty/issues/2982). This added a feature through which we can override grades in gradeable with a very simple GUI. + +- [[Feature:InstructorUI] Revise Grade Override for clarity](https://github.com/Submitty/Submitty/pull/4363) +- [[Feature:InstructorUI] Grade override](https://github.com/Submitty/Submitty/pull/3998) + +#### 4. Discussion Forum + +This is the list on my contribution in discussion forum side of the Submitty. It includes some minor Bugfixes with some new features. + +- [[Feature] TA/Instructor can lock Thread](https://github.com/Submitty/Submitty/pull/3703) +- [[FEATURE]Chronologically Descending Sorting option](https://github.com/Submitty/Submitty/pull/3655) +- [[BUGFIX]Fix unhandled exception when no thread in discussion forum](https://github.com/Submitty/Submitty/pull/3622) +- [[Bugfix] Trim spaces in forum thread titles](https://github.com/Submitty/Submitty/pull/3520) +- [[BUGFIX] Fix size of textarea when editing post](https://github.com/Submitty/Submitty/pull/3498) +- [[Bugfix]Aligning select color tag in 'Edit categories'](https://github.com/Submitty/Submitty/pull/3463) + +#### 5. Small Bugfixes + +This are the list of bugfixes in different places in Submitty. + +- [Remove raw in course setting page](https://github.com/Submitty/Submitty/pull/3972) +- [[Refactor] Replace deprecated {\% for ... if ... \%} with filter in twig ](https://github.com/Submitty/Submitty/pull/3971) +- [[Bugfix] Validating URL for course home page](https://github.com/Submitty/Submitty/pull/3947) +- [[Bugfix] Stop fading of error messages](https://github.com/Submitty/Submitty/pull/3910) +- [[Bugfix]Changing late days to default late days](https://github.com/Submitty/Submitty/pull/3891) +- [[BUGFIX] Improve student validation for late days allowed](https://github.com/Submitty/Submitty/pull/3886) +- [Aligning submission selection form using flex](https://github.com/Submitty/Submitty/pull/3758) +- [[BUGFIX] Highlighting checkbox label on focus](https://github.com/Submitty/Submitty/pull/3538) +- [[BUGFIX] Fix size of textarea when editing post](https://github.com/Submitty/Submitty/pull/3498) +- [Add shortcut(KeyD) for discussion panel in grading portal](https://github.com/Submitty/Submitty/pull/3493) +- [Fix css of button for regrade request](https://github.com/Submitty/Submitty/pull/3483) +- [Removing extra space in grading discussion portal](https://github.com/Submitty/Submitty/pull/3481) +- [Apply trim to frontend and backend in Authentication](https://github.com/Submitty/Submitty/pull/3478) +- [Add stoplight legends to grade details page](https://github.com/Submitty/Submitty/pull/3381) +- [Error Handling on Login Page](https://github.com/Submitty/Submitty/pull/3358) + +## Future Scope of Work + +Presently Assignment Autograding can generate both random inputs and outputs with option of generating non random output at time of build of gradeables.But there is some room for improvement inorder to enhance the functionality:- + +* Presently we can only generate output and input using only python scripts. Ideally assignment should generate output and input using every programming language. + +* Tests for random inputs and output should be added to check if something has not broke random inputs and outputs + +## Acknowledgments + +I had an overwhelming summer contributing in Submitty through [Google Summer of Code](). I am really obliged and thankful to [Barbara Cutler](https://github.com/bmcutler) and [Evan Maicus](https://github.com/emaicus) for mentoring me throughout the course of program. I am really thankful to [Peter Bailie](https://github.com/pbailie), [Matthew Peveler](https://github.com/masterodin), [Shail Patel](https://github.com/shailpatels) and all other student at RPI working in RCOS and GSoC. + +Submitty has playe a crucial role in developing my interset in open source world. Every time I will think about open source Submitty will be first word which will come in my mind. \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/2019_FonNoel.md b/_docs/developer/google_summer_of_code/2019_FonNoel.md new file mode 100644 index 00000000..60037eb7 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2019_FonNoel.md @@ -0,0 +1,90 @@ +--- +title: Fon Noel +category: Developer > Google Summer of Code 2019 +--- + +# GSOC 2019 REPORT: Continuous Integration Testing (Automation) for Submitty +

+ +

+ The aim of this project is to expand the code coverage of the unit and integration tests for Submitty codebase. + +### Background and Requirements + + From the beginning we observed a couple of problems and chanllenges including : + 1. Travis had become to very suitable for the complex Submitty structure. Which holds code in multiple languages + 2. The times taken to complete builds are/were quite significant for travis. + 3. Submitty code needs more and more tests, i.e we have to increase the code coverage and enforce practices to maintain its growth. + 4. We should be able to get a global view of what the system code coverage, in essence having a single coverage report for all languages. + + To achieve this feet, I and my project mentors [Matt Peveller](https://github.com/MasterOdin) and [Barb Cutler](https://github.com/bmcutler) decided on the following work that had to done. + +* Find tools that are suitable for Submitty's needs and can replace Travis nicely. + + *I found and suggested Buildbot which proved highly suitable for our complex needs* +* Migrate gradually from Travis to this tool (Buildbot). +* Work on issues on the Submitty main repository as a way to complement work being done with configuring an new continues integration framework. + +*Since this work is just about architecture we also discussed extensively possibilities of completely having Submitty run on docker and not just the ubuntu VMs which take a lot of time to set up and to do tests when working with.* + +### Expectations + +As a result, we expected Buildbot, the highly configurable Continues Integration and Automation tool which we could maneuver to get certain not so common task done for us. This include: + - Move some build and test operations to Buildbot and disable them from Travis at least by the end of GSoC. + - Run all of significant parts of Travis on docker as part of the Buildbot work but also as an expirement to explore possibilities of using docker as an architecture for Submitty. + - Reduce bugs on Submitty or introduce new features via open issues and PRs. + +# Results + +## 1. Buildbot + +In general, I was able to set up and have Builbot run builds on pull requests and also changes to the master branch. + +The major things are achieved here are : +- Breakdown and separation of builds, so using thesame concept of build stages distinct sections such as the `migrator`, `site`, and `autograder` where assigned independent Builbot bulders which run more concurrently. +- There's a dramatic increase in the speed of builds. In practise from between 10mins to 2 hours to less than 5 minutes for the parts that were moved. + +

+ + +*A Submitty pull request showing 4 newly introduced builders powered by buildbot* +

+ +#### References + +* **[Buildbot Set Up Repository](https://github.com/Submitty/submitty-buildbot/)** (Code and Configuration) + +* **[Running Buildbot Setup](http://submitty-ci.cs.rpi.edu/)** (Live) + + +## 2. Submitty PRs + +To complement work being done on Buildbot, and also to help me understand the structure of Submitty I had to work on a couple of issues. Most of the work, was related to modifying the python script to improve some aspect of automation. + +#### References, major tasks + +* Modified python scripts related to generating Sample data for TA notes. [#3885](https://github.com/Submitty/Submitty/pull/3885) +* Added generation of cancelled submissions in sample data. [#3848](https://github.com/Submitty/Submitty/pull/3848) +* Implemented shorchut buttons for the flatpick date picker. [#3963](https://github.com/Submitty/Submitty/pull/3963) +* Fixed stream errors on Forensics page. [#4053](https://github.com/Submitty/Submitty/pull/4053) + +Amongts a couple of [other issues](https://github.com/Submitty/Submitty/pulls?utf8=%E2%9C%93&q=+is%3Apr+author%3AFenn-CS+), some of which are yet to be completed. + + +## Future Work + +Following various obstacles faced, during the period of GSoC and various areas spotted for improvement there is more work to be done. + +For builbot, we agreed to document the work that needs to be done to improve it's functionality based on constraints from my end and limitations of Buildbot itself via the use of open issues. + +#### References + +Buildbot Future Work: [Issues tagged [future-work]](https://github.com/Submitty/submitty-buildbot/issues?q=is%3Aissue+is%3Aopen+label%3Afuture-work) + + +## Thanks Submitty! + +Working with and on Submitty, has been a great experience for me. I was greatly motivated by the "killer" sysadmin and problem solving abilities of my mentor **Matt Peveller** and the highly friendly, supportive and flexible environment created by **Barb Cutler** our GSoC admin. + +Many thanks to [Shail Patel](https://github.com/shailpatels), all the GSoC participants and everyone at Submitty. + diff --git a/_docs/developer/google_summer_of_code/2019_XiaoHan.md b/_docs/developer/google_summer_of_code/2019_XiaoHan.md new file mode 100644 index 00000000..b209f5e9 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2019_XiaoHan.md @@ -0,0 +1,50 @@ +--- +title: Xiao Han +category: Developer > Google Summer of Code 2019 +--- + +# REST API for Submitty + +The project aims to establish a REST API for Submitty. The API provides an alternative way of interacting with Submitty, which helps system administrators write scripts to automate database operations, enables developers to work out their front-ends and facilitates tests for methods that previously only return fully rendered pages. + +The project mainly consists of two parts: replacing the original router of Submitty and implementing API endpoints. + +The project is carried out by [XIAO Han](https://github.com/zjxiaohan), an undergraduate student from [Zhejiang University](http://www.zju.edu.cn/english/), as part of [Google Summer of Code](https://summerofcode.withgoogle.com/). + +### Contributions + +Contributions are outlined as follows: + +- [Over 100 commits](https://github.com/Submitty/Submitty/commits?author=zjxiaohan) are made to the main repository of Submitty. +- [Several commits](https://github.com/Submitty/submitty.github.io/commits?author=zjxiaohan) including new documents along with some other minor modifications are made in the repository of Submitty documentation. +- [Home for the documentation for the Submitty API](https://github.com/Submitty/api.submitty.org) is created with the help of the mentors. + +#### a. Router Replacement + +The routing mechanism of Submitty was simple. It makes use of the query string attached to the URL to determine which page to return, which unfortunately produces lengthy and unreadable URLs. While that routing approach worked in the past, the need of API calls for a more clear URL structure. + +During the summer, a new router is used and all URLs of Submitty are replaced with new ones. The task is fairly demanding considering the sometimes heterogeneous coding style across Submitty, the extensive nature of critical methods (which entails painful merge conflicts and urgent bug fixes) as well as the constant need to refactor the router as unanticipated problems arise. + +The continuous improvements and extension of the router being many, it would be trivial to include a list of pull requests in the report. Please refer to the [router documentation](/developer/router) for more information. + +#### b. API Implementation + +Basic API framework for Submitty has been set up. It is simple for developers to set up API endpoints without writing redundant code. Currently, an API token [can be obtained](https://api.submitty.org/#get-token) by users, which is later used for getting a list of [courses](https://api.submitty.org/#get-courses), [students](https://api.submitty.org/#get-users) or [graders](https://api.submitty.org/#get-graders). Please read the [API documentation](https://api.submitty.org/) for more information. + +It is also worth to mention that the API is proved useful for making [a working-in-progress tool for nightly run of generating grade reports](https://github.com/Submitty/Submitty/issues/3711). More creative usages of API are to be explored by future developers. + +### Future Work + +An API opens a world of possibilities. Here is a list for future developers. Feel free to come up with new ideas yourself. + +- Help implement more API endpoints to enrich Submitty API. After carefully reading [suggestions for new developers](/developer/getting_started/index#suggestions-for-new-developers), you can start writing new endpoints hosted at Submitty that can direct your robot to wash the dishes and fold the laundry. +- Develop plugins for text editors so that you can autograde your work without switching between windows. +- Build *your* Submitty application. While sharing data with Submitty, you can rebrand it with your name (like Shailmitty), repaint and reshape everything with your genius aesthetic tastes without fighting with picky people, and even, develop an Android or iOS application that makes everyone forget the web version and keeps Barb on vacation every day. + +### Acknowledgments + +I would like to express my gratitude to Matt Peveler for his patient guidance and valuable insights. I would also like to thank Barb Cutler for her effective organization and essential perspectives and contexts she provides. + +Thanks should also be given to Preston Carman for his constructive suggestions and warm encouragements throughout this summer. + +Furthermore, my thanks are extended to RCOS students and other GSoC students I am working with during the summer. It has been a great experience working at Submitty! \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/2020_Harsh_Joshi.md b/_docs/developer/google_summer_of_code/2020_Harsh_Joshi.md new file mode 100644 index 00000000..95e037df --- /dev/null +++ b/_docs/developer/google_summer_of_code/2020_Harsh_Joshi.md @@ -0,0 +1,81 @@ +--- +title: Harsh Joshi +category: Developer > Google Summer of Code 2020 +--- +# Peer Grading +Peer grading feature at Submitty establishes the concept of students grading other students which was aimed to increase the quantity and diversity of detailed feedback on student assignments and presentations along with facilitating students to see other ways of approaching a problem, and asking important questions about the effectiveness of those alternate methods. +The idea of peer grading has been introduced in some e-learning platforms but is still governed by rubrics for evaluation. Submitty brings a fresher perspective to this idea. The concept in itself is revolutionising and brings in the opportunity for peer grader to engage with and analyze work which adds to a part of the learning. Peer grading also eliminates the need for evaluation at scale. + +# About +My Name is [Harsh Joshi](https://linkedin.com/in/josharsh). I am a computer science undergradute from the University of Petroleum and Energy Studies. +The project was under the mentorship of [Barbara Cutler](https://www.cs.rpi.edu/~cutler/), [Evan Maicus](https://github.com/emaicus) and [John Hulton](https://github.com/jchulton). +### [Submitty](http://submitty.org) +**Homework Submission, Automated Grading, and TA grading system** + +GitHub : [https://github.com/Submitty/Submitty](https://github.com/Submitty/Submitty) + +# Contributions + +## Randomized Peer Assignments +Randomized assignments of peer graders in a class was an upgrade from manual csv upload of the peer grading matrix. This feature enables using GUI interface to prepare a random assignment where each student grades *n* random students (and also receives feedback from *n* random students). + +## Bug fix on grading index stats +Upgraded grading index to take peer grading statistics for calculation of Manual Grading total. Fixed bugs involving maximum total for manual grading score and final score. + +## Stoplights Upgrade +The white, green, yellow, blue, and purple stoplights indicate grading progress per submission. My work included restricting peer graders from accessing non peer stoplights and upgrading stoplights for gradeables with both peer and non peer components. + +## Grading Statistics +The grading stats on the status page show relevant grading figures including number of students who submitted, number of assignments which have been graded, grading stats by registration, and data on average scores etc. My work included to upgrade grading figures for peer gradeables with access to peer grading stats on student and non student views, and fix bugs on incorrect grading data for gradeables with mix of peer and non peer components. + +## Options for peer matrix +Peer matrix options allow to configure the peer grading assignments. My work on options for peer matrix included restricting the assignments to each registration section, downloading peer matrix as csv, clearing the peer matrix, and writing feature to enable every student grading every other student. + +* **All Grade All** option sets the peer matrix such that each student grades every other student in a class. + +* **Restrict to Registration** restricts the peer grading assignments to each registration section which means only students in a registration section will be grading each other. + +* **Submit before grading** enables the instructor to allow grading to only those students who have submitted their own assignments. Note that this option should only be used when sufficient submissions have been made, usually after the submissions are closed. + +* **Download Peer CSV** exports the current peer matrix to csv which can be reuploaded for future/other peer assignments. + +* **Clear Peer Matrix** resets the current peer matrix. Note that this option should be used carefully when randomized peer assignments are used as it can't be undone. + +## Introducing peer gradeables on sample course. +Sample course contains sample data which is used for various development purposes including testing. As a part of my work I wrote code to introduce peer gradeables to the sample course. + +## Refactoring peer grading assignment function. +Optimized and modularized peer grading assignment function to better suit the unit testing needs. + +## Optimized Queries for peer matrix. +Wrote database queries and server side logic to optimize time take to set the peer matrix via upload csv method. The updated logic uses optimized sql queries along with bulk upload function to reduce the number of server interactions with the database and pushed data at one go. + +## Randomized peer assignmend in sample course +Implemented the randomized peer assignments logic for the sample peer gradeables in the sample course. + +## Documentation +Wrote documentation at submitty.org for +* Upgrade to pip3 +* Handling caching in Twig Files +* Using options for peer matrix + +## Review +Reviewed pull request of fellow developers which included PRs on +* Late submission check +* Adding new grader to the peer matrix +* Editing peer matrix +* Upgrading download zip feature for peer gradeables +* Peer annonymization in sample course + +# Future Scope +Peer grading has a lot of scope for future work. Some of the ideas for future work include - +* **Notifications**: + * **Peer Grading**: Currently students are not notified if they need to peer grade (after grading has been opened) or Grading has been opened and there are peer components to grade. + * **Due Date Approaching** : When the due date of an assignment is very near (say 2 days) it might be good to give a friendly reminder to students. This can also be applied to reminders to peer grader right before grades are to be released. +* **Separate Logic from templates on grading stats page**: +Twig files have a lot of javascript written in them in grading which makes it verbose. This also applies to the recently updated peer grading assignments page. Such pages could be cleaned up a bit more so that fresh eyes looking into the code understand it at the first go. + + +# My Experience of GSOC with Submitty +Submitty is a live project and being able to work on a project that is being actively used by hundreds of students and teachers has been fascinating. To work with developers across regions, careers and skillset was equally motivating. Working with developers and mentors at Submitty brought in new perspectives and gave me insights on being a better developer. While I worked at Submitty, I got to experience open source culture from close quarters, work around developing real solutions, introspect my own work and skills, contribute to open source and be a better at work. I enjoyed every bit of it. To put my work right to meet the expectations of the community was challenging and rewarding. Thorough code reviews with more than one pair of eyes looking gave me valuable insights and feedback. +Whenever I had slow progress the mentors were extremely helpful and empathetic. From 1v1 meetings to discussions on slack, emails and PR threads, I am grateful for the additional help and support. diff --git a/_docs/developer/google_summer_of_code/2020_Marwan_Atef.md b/_docs/developer/google_summer_of_code/2020_Marwan_Atef.md new file mode 100644 index 00000000..da0de04f --- /dev/null +++ b/_docs/developer/google_summer_of_code/2020_Marwan_Atef.md @@ -0,0 +1,115 @@ +--- +title: Marwan Atef +category: Developer > Google Summer of Code 2020 +--- + +# WebSockets for live page updates + +You can find all my merged PRs in [this link](https://github.com/Submitty/Submitty/pulls?q=is%3Apr+author%3Amarwanatef2+is%3Amerged). + +--- +## Why? +###### Why do we need websockets? + +WebSockets allow users' pages to get dynamically refreshed/updated without the need to manually refresh the page every now and then. +This behaviour is useful in pages that are accessed by multiple users simultaneously. So, new updates are fetched automatically and only the necessary parts of the page are re-rendered without refreshing the whole page to get the updates reducing the load on the server. + + --- +## What? +###### Which pages use websockets so far? + +4 pages are currently getting updated using websockets: + +### 1. Discussion Forum + +Nearly all forum-related functions use websockets: +* Thread-related: *[#5529](https://github.com/Submitty/Submitty/pull/5529)* + 1. Create new thread + 2. Delete thread + 3. Resolve thread + 4. Announce thread + 5. Merge two threads + +* Post-related: *[#5594](https://github.com/Submitty/Submitty/pull/5594)* + 1. Add new post / reply + 2. Modify post + 3. Delete post + 4. Split post + +In this gif a new thread is created on one user's window and the update is reflected on the other window, new posts are added and thread is marked as resolved. +![Discussion forum demo](../../../images/MarwanAtef_GSoC/forum.gif) + +### 2. Office Hours Queue + +The office hours queue is currently fully working with websockets instead of polling (Check for updates on a time interval of 30 seconds): *[#5660](https://github.com/Submitty/Submitty/pull/5660)* +1. Join / Leave queue +2. Remove student from queue +3. Restore student +4. Add / modify announcement + +An example of the office hours queue working with websockets +![Office hours queue demo](../../../images/MarwanAtef_GSoC/OHQ.gif) + +### 3. Grade Inquiry + +A student can open a grade inquiry for a gradeable if allowed, the grade inquiry is much like the discussion forum and is fully working with websockets as well. *[#5765](https://github.com/Submitty/Submitty/pull/5765)* +1. Post additional information +2. Respond and resolve inquiry +3. Close / reopen inquiry +4. Add comment + + +### 4. Checkpoint & Numeric Grading + +Both the checkpoint and numeric grading are working with websockets but there is still some area for improvement. *[#5829](https://github.com/Submitty/Submitty/pull/5829)* + +An example for the checkpoint cells updating with websockets +![Checkpoint grading demo](../../../images/MarwanAtef_GSoC/checkpoint.gif) + +--- +## How? +###### How websockets work? + +1. Users open websocket clients when document is ready. +2. User 1 makes a request (eg. *reply to a post*) +3. Upon request success, user's websocket client sends a socket message indicating that there is an update (eg. `{'type': "new_post", 'post_id': #id}`) +4. The websocket server broadcasts / forwards the socket message to all other users (websocket clients) on the same page. +5. Other websocket clients receive the socket message. +6. Upon message receiving users call the associated function depending on the message type mentioned above (eg. `SocketNewPostHandler()`) +7. The associated function makes an Ajax request to fetch the new post and place it in the correct place in the DOM. + +#### References + +* [WebSocket CLient wrapper](https://github.com/Submitty/Submitty/blob/master/site/public/js/websocket.js) `websocket.js` +* [WebSocket Server](https://github.com/Submitty/Submitty/blob/master/site/app/libraries/socket/Server.php) `Server.php` +* [PHP WebSocket Client](https://github.com/Submitty/Submitty/blob/master/site/app/libraries/socket/Client.php) `Client.php` + +For the above explained example: +* [WebSocket initialization function](https://github.com/Submitty/Submitty/blob/master/site/public/js/forum.js#L587-L638) `initSocketClient()` +* [Message sending](https://github.com/Submitty/Submitty/blob/master/site/public/js/forum.js#L203) +* [The message handler (callback function) ](https://github.com/Submitty/Submitty/blob/master/site/public/js/forum.js#L241-L295) `socketNewOrEditPostHandler()` + +--- +## Future Work + +WebSockets open multiple areas for development / improvement including but not limited to: +* **Discussion forum** +Currently, New posts are added with websockets for *"tree"* view only, posts can be sorted chronologically or alphabetically as well, see issue [*5683*](https://github.com/Submitty/Submitty/issues/5683) + +* **Complex Rubric Grading** +The rubric grading page is accessed by multiple TAs simultaneously, suggestions may be: + * Update the page when any TA makes any change. + * Have a small panel at the top indicating all online TAs (having an open websocket client) and colored cursors indicating where or which part (component) they are editing/grading (eg. *Google Docs*) + +* **Jobs Daemon Queue** + +* **Autograding Queue** + +* One other functionality that can be added is to send browser notifications on socket messages. + +--- +## Acknowledgment + +I'm very grateful for spending the summer coding with Submitty, I would like to thank **Barb Cutler**, Submitty Admin, for this amazing period and the awesome organizing and her flexibility, I would also like to thank all my mentors **Andrew Aikens**, **Matthew Peveler**, **Kevin McKinney** and **Shail Patel** for their constant guidance and their quick response. + +This summer with Submitty was an unforgettable experience, whenever I'm asked for a recommendation on open source contribution or GSoC Submitty will be the first thing to come to my mind. diff --git a/_docs/developer/google_summer_of_code/2020_Mukul_Kumar_Jha.md b/_docs/developer/google_summer_of_code/2020_Mukul_Kumar_Jha.md new file mode 100644 index 00000000..8d4abd07 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2020_Mukul_Kumar_Jha.md @@ -0,0 +1,157 @@ +--- +title: Mukul Kumar Jha +category: Developer > Google Summer of Code 2020 +--- + +![GSoC image](/images/GSoC.png){: .center-image } + +### Mobile-Friendly Website and Progressive Web App (PWA) + + +This project was focused on making submitty mobile friendly and a progressive web-app with adding push notification feature but during the summer I worked equally on number of other features which involved adding and updating database, writing SQL queries and adding corresponding migrations file. I also added unit tests for different Models and used Selenium (with python) to write end-to-end tests. + + +To sum things up, this was a great full-stack project and I enjoyed working on all the major parts of Submitty! + +1. Designs, created designs for new TA grading interface and some other mobile-focussed components and iterated over it based on awesome feedback from the entire Submitty team :). +Tool Used: Figma +2. Views (Frontend), improved existing User interface, made pages compatible with different screen sizes and added some new interfaces also. +Tech Used: Figma, HTML, Twig, CSS, Bootstrap, JS, JQuery, Service-Workers +3. Models and Controllers (Backend), worked on different models and played a lot with database while adding new pages, views and implementing new feature requests. +Tech Used: PHP, PostgreSQL, Datagrip, SQLAlchemy, Vagrant +4. Testing, during the summer I added unit-tests for the Models which were not covered by tests and also added end-to-end tests. +Tech Used: Selenium, Python, PHPUnit, TravisCI + + +#### About Me + +Hello, I'm [Mukul Kr Jha](https://www.linkedin.com/in/mukul-kr-jha/), final year computer science student from Ambedkar Institute of Advanced Communication & Training Research (GGSIPU) and this summer I worked under Submitty organization as a GSoC student. + + +#### Pull Requests + +Following listed Pull Requests were created during the GSoC timeline under this project. I have listed brief points for some of the PR below and for more information and/or code implementation please follow the link I have attached with + +- [[Feature: InstructorUI] New TA grading Interface](https://github.com/Submitty/Submitty/pull/5543) + + * Added new interface for TA grading page with the fixed layout structure + * Added single panel mode view for normal grading. + * Added two-panel-mode with drag-bar to adjust the width and resize the panels for power users of this interface. + * Added full-left-column-mode where left column of the two-panel mode takes full height of the window. + * Added another power user mode full-screen-mode or focus-mode in which the grading interface goes full screen and there is no side-nav-bar or top nav bar, + * Retained all the Ta-Layout detail even when instructor switched to new student and/or refreshes the page. + +- [[Feature:TAGrading] Layout selector modal](https://github.com/Submitty/Submitty/pull/5831) + + * Replaced switching between different panel from the toggler button to providing all the available panels at once + * To improve the UI/UX of TAGrading page I added a mini-view of all the panel-modes using HTML Canvas + + +- [[Feature:TAGrading] 3 panel mode](https://github.com/Submitty/Submitty/pull/5759) + + * Introduced the third panel in the TA grading interface. + * Added the resizing for the horizontal panels with the help of provided drag-bar. + +- [[Feature:TAGrading] Add Solution/Ta Notes Panel](https://github.com/Submitty/Submitty/pull/5801) + + * Added a new panel "Solution/Ta-Notes" to let instructors share solutions and specific notes with other instructors. + * For each component rubric their is a corresponding solution component. + * Shows when a particular component was last edited and who was the author. + +- [[Feature:InstructorUI] Notebook itempool solution/ta-notes rubric](https://github.com/Submitty/Submitty/pull/5840) + + * This feature is only for those notebook gradeables which has itempool randomization enabled (having one or more notebook item with multivalued `from_pool` ) + * Added an option to enable or disable linking a particular component rubric with this itempool items which support randomization. + * Integrated itempool support for `Solution/TA notes` panel. which made grading different student with different items very easy. + +- [[Feature:Notebook] item_pool map student to problem](https://github.com/Submitty/Submitty/pull/5719) + + * Added support for the `user_item_map` (optional field), + * Users in this mapping only will be shown item corresponding to the mentioned index next to their username and no hash based randomization will be done them + * Helped instructors proofread and test all the items. + +- [Plagiarism refactor and mobile page](https://github.com/Submitty/Submitty/pull/5516) +- [[UI/UX:InstructorUI] Plagiarism full screen & resizable panels](https://github.com/Submitty/Submitty/pull/5611) + * Refactored plagiarism module code, improved the MVC design flow and synced it with the existing codebase. + * Made plagiarism pages compatible across different sized screens. + * Added full screen display and drag-bar to adjust width of the codebox panels. + +- [[Feature:Instructor-UI] Add an open date for grade inquiry](https://github.com/Submitty/Submitty/pull/4885) + + * Added `grade inquiry open date` to let students start posting their grade inquiry. + * Updated database to start supporting `grade inquiry open date` + * Update all the sample courses `YAML` files to have this newly added date. + +- [[Feature:UI/UX] user profile settings page](https://github.com/Submitty/Submitty/pull/5671) +- [[Testing: UI/UX] E2E test for profile page](https://github.com/Submitty/Submitty/pull/5815) + + * Introduced user profile page, where they view and update their various information (basic info, profile photo, time-zone and theme to use) + * Added a single time-zone drop down list with UTC offset value attached to it and sorted in increasing order wrt UTC offset values to let users find the best-suited time-zone quickly. + * Added end-to-end test in Selenium to make sure everything works cool. + +- [[Testing:PHP] Add testcases for some PHP classes](https://github.com/Submitty/Submitty/pull/5574) +- [[Testing:Notification] Add testcases for Notification model](https://github.com/Submitty/Submitty/pull/5547) + * Wrote Unit tests in PHPUnit for the Post Model, SimpleGradeOverriddenUser, SimplelateUser model and Notification Model. + +- [[UI:Submission] Mobile view for submission page](https://github.com/Submitty/Submitty/pull/5432) + +- [[UI:InstructorUI] Add small screen view for the TA index page](https://github.com/Submitty/Submitty/pull/5418) + +- [[UI: InstructorUI] Mobile view for grade-override](https://github.com/Submitty/Submitty/pull/5417) + + +- [[MobileUI: TaGrading] Adds Mobile UI for the TA Grading page](https://github.com/Submitty/Submitty/pull/5611) + +- [[UI:Mobile] Add mobile screen view for the grade-report page](https://github.com/Submitty/Submitty/pull/5409) + +- [[Feature:MobileUI] Add Collapsible gradeables](https://github.com/Submitty/Submitty/pull/5396) + +- [[Feature: Instructor UI] XLSX/CSV Grader and Student Upload Need Better Error Messages](https://github.com/Submitty/Submitty/pull/5133) + +#### WIPs / Blocked +- [[Feature: Forum] Full page forum to browse threads](https://github.com/Submitty/Submitty/pull/5726) + * Add a landing page for the forum threads to let users select from all the available threads + * Added filters on this page refine the search and find the targeted thread easily. + +- [[Feature: Submitty] Progressive web-app and push notification](https://github.com/Submitty/Submitty/pull/5856) + * Make Submitty installable on all the major platform as an app (PWA) + * Enable Push notification (in addition to all the onsite-notification which have currently) to keep students and instructors informed with latest development across all the courses. + +- [[Refactor: InstructorUI] Remove support for old TA-grading interface](https://github.com/Submitty/Submitty/pull/5859) + * Remove the legacy interface from Submitty and update route to use the new Interface as default one. + * Refactor and code cleanups in response to the above change. + + +##### Small Bugfixes + +- [[Bugfix:TAGrading] Next/prev when grading done](https://github.com/Submitty/Submitty/pull/5664) + +- [[Bugfix: Notebook] Notebook header collapsing on Safari](https://github.com/Submitty/Submitty/pull/5814) + +- [[Bugfix: InstructorUI] Enable discussion component](https://github.com/Submitty/Submitty/pull/5773) + +- [[Bugfix: Autograding] Side by side display autograding diff results](https://github.com/Submitty/Submitty/pull/5658) + +- [[Bugfix:TAGrading] new interface - view submitted files](https://github.com/Submitty/Submitty/pull/5764) + +- [[Bugfix:InstructorUI] Excused absence extensions won't submit ](https://github.com/Submitty/Submitty/pull/5470) + + +#### Documentation + +Here are some of [my PRs](https://github.com/Submitty/submitty.github.io/pulls/mukul-kmr-jha) adding /updating Submitty's documentation + + +#### Future Scope + +- There is lot of room for improvements in Forum code +- Increasing test coverage for the entire Submitty codebase +- Making Submitty UI even more better, engaging and pixel-perfect. + +#### Overall Experience + +I got introduced to Submitty last year and from the very beginning, I loved the Submitty's objective and friendly environment, thanks to [Matthew Peveler](https://github.com/MasterOdin) for helping me with the onboarding and valuable feedbacks through your reviews. +I am very thankful to [Barbara Cutler](https://github.com/bmcutler), Submitty, RPI, and the GSoC team for giving me this chance and for bringing in this amazing experience full of learning and fun. +Complete project involved a lot of learning and challenges. I loved collaborating with RPI faculty and students and enjoyed working on the project used by not only RPI but a number of other universities across the globe. +During the whole summer, all of my project mentors were super awesome and super supportive and I learned a lot from them. Special thanks to [Barbara Cutler](https://github.com/bmcutler), [Eli Schiff](https://github.com/elihschiff), [Shail Patel](https://github.com/shailpatels), [Evan Maicus](https://github.com/emaicus), [Matthew Peveler](https://github.com/MasterOdin). They helped me with designing the new interface and gave me interesting developer tips during the whole project, I also enjoyed reviewing other developers code. +It was a really great experience working and interacting with all the passionate RPI developers and fellow GSoC developers during the meeting we have had. diff --git a/_docs/developer/google_summer_of_code/2022_Akshat_Batra.md b/_docs/developer/google_summer_of_code/2022_Akshat_Batra.md new file mode 100644 index 00000000..512ef6b4 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2022_Akshat_Batra.md @@ -0,0 +1,109 @@ +--- +title: Akshat Batra +category: Developer > Google Summer of Code 2022 +--- +# Website Security and Penetration Testing + +Security of any website is very crucial but in case of Submitty, writing secure code becomes all the more essential because of the nature of this software. Grades of students depend on the security of the website; just one loophole is enough to give a student an academic advantage over others. Dealing with student data comes with legal implications that require particular security standards. It must be ensured that proper access control and authorization practices are in place. Keeping all this in mind, the following work was done by me during the summer: + +[See commits](https://github.com/Submitty/Submitty/commits/main?author=akshatbatra) + +[See pull requests](https://github.com/Submitty/Submitty/pulls?q=is%3Apr+author%3Aakshatbatra) + +--- + +## Session Management + +[PR #8284](https://github.com/Submitty/Submitty/pull/8284) + +I developed a session management page using which a user can view his/her active login sessions and terminate any dangling sessions. As part of this, another unique feature of enforcing single session was added. A user can set this secure session setting and then he/she will only be able to have one active session at any given time. +Whenever a user logs in, the following information is recorded: +1. Platform (e.g. Win10) +2. Browser name (e.g. Chrome) +3. Browser version (e.g. 104.0) + +**Use case:** Let's assume that by some way (phishing attack, key logging etc.), a bad actor gets hold of the credentials of a high privilege user e.g. instructor. Now, before the addition of this page, that bad actor could log-in and access all the time-sensitive academic information (gradeables, unreleased exam solutions in course materials etc.) undetected. But now, as all the sessions are visible on the interface, a smart user can identify if their account has been compromised by looking at the login timestamp, platform and browser information. He/she can then take necessary actions such as immediately terminating all other sessions by just clicking a button and then changing the password. + +**Future Scope:** This doesn't completely eliminate the possibility of account hijacking, but is still a good step towards early identification in a number of cases. When using SAML authentication, identity provider may already have some suspicious login detection mechanism in place, there can be discussion on whether Submitty should have its own such mechanism or not. + +--- + +## Unmasking the identity + +[PR #8002](https://github.com/Submitty/Submitty/pull/8002) + +**Context:** Submitty already had a concept of anonymous ids. Submission of every student can be identified by a unique anonymous id tied to him/her. This is useful to eliminate partiality while grading. This is a must have for peer grading so that students don't grade each other based on their perceptions and personal conflicts but instead grade every submission with a neutral mindset. This feature is useful to counter any subconscious preference when limited access graders are concerned. If the grading is blinded, students can be assured that the chances of their grades being biased have drastically decreased. + +**Problem:** Until now, everything sounds good. But here comes the issue: anonymous ids are generated one time and used for all gradeables within the course, so if a user somehow gets to know the anonymous id of another user then they can identify that user forever (including past and future gradeables) while grading. Consequently, the purpose of anonymous id is defeated and grading doesn't remain fully anonymous anymore as the identity of the submitter gets compromised. + +**Solution:** New anonymous ids are generated for each gradeable, if an anonymous id is compromised for one gradeable, the impact is much less as the future gradeables will have different randomly generated anonymous ids for all the course users. It sounds simple, but anonymous ids are deeply embedded into Submitty. A number of issues unearthed themselves as part of this work; they were handled with sword in one hand and armor in the other. **The bottom line is that this work diluted the side effects of unintended disclosure of personally identifiable information.** + +--- + +## Achilles' heels + +Following vulnerabilities were patched (get ready for some peculiar titles): + +#### Release it NOW + +[PR #8188](https://github.com/Submitty/Submitty/pull/8188) + +Instructors may use course materials functionality to release homework solutions or assignment solutions that have weightage in the term grades. Broken access control allowed any user (including any student) to release all the course materials and then view the solutions. + +#### Hide & Seek + +[PR #8150](https://github.com/Submitty/Submitty/pull/8150) + +Course materials have a "Hide material" feature. Using this feature doesn't actually prevent the students from accessing the materials. During the assessment, I learned that students can access the hidden files leveraging insecure direct object reference. But, this feature never intended to protect the materials from being accessed. Only release date of the material should be used for the purpose of setting the access status. As this can be confusing for the instructors, a proper warning is issued now whenever "hide material" feature is used. + +#### Grading mania + +[PR #8383](https://github.com/Submitty/Submitty/pull/8383) + +Feeling bored? Let's grade all the students in the class! +This vulnerability is related to peer grading assignments, it was discovered and brought up by Matt B., if the anonymous id of a submitter is known then any peer could grade them even if he/she was not assigned to grade that submitter, a student could also possibly grade their own submission. + +#### I was there before you! + +[PR #8229](https://github.com/Submitty/Submitty/pull/8229) + +Have you ever been in a dispute about your position in a queue? A vulnerability was discovered leveraging which a student could remove another student from an office hours queue, then the former could be present in two queues at the same time. + +#### Keep it coming - I + +[PR #8054](https://github.com/Submitty/Submitty/pull/8054) + +A student could upload unlimited number of profile photos. Without other protection measures in place, even a low privilege user could fill up the server's storage. A limit has been imposed now. + +#### Keep it coming - II + +[PR #8051](https://github.com/Submitty/Submitty/pull/8051) + +There was no file format restriction for profile photos; this left the doors wide open for several unexpected behaviors/vulnerabilities (such as those related to SVG files). A profile photo is supposed to be small in size, but there was no limit (other than in PHP configuration) on the size of profile photo that the server would accept for processing. Now only some select image formats are allowed and a limit has been imposed on the file size. + +#### There's a limit to everything + +[PR #8230](https://github.com/Submitty/Submitty/pull/8230) + +Max nesting level wasn't enforced for Markdown. Due to this, max recursion depth was reached when provided with particular Markdown input to render, causing the pages with rendered Markdown to be totally inaccessible in the worst scenario. A student could trigger this behavior in discussion forum. + +#### A peek inside + +[PR #8231](https://github.com/Submitty/Submitty/pull/8231) + +Students and limited access graders could view the details about the progress of bulk grading job, in addition to that, they could access the statistics/forensics related to bulk grading. + +## Side business: + +[PR #8216](https://github.com/Submitty/Submitty/pull/8216) + +I felt the necessity of being able to view the common settings (if any) for a folder i.e. common release date, common section(s) and common "hide materials" setting. To accomplish this I developed a client side solution to recursively traverse the folder structure of course materials page to determine the settings that were common in all files/folders within each folder. + +I also reviewed pull requests by other developers; it was a very pleasant experience. + +## Acknowledgements + +This has been one of the best experiences of my life. I would like to thank Dr. Barb Cutler and Chris Reed for supporting me at every step. Dr. Barb is an exceptional thinker, academician and leader; she possesses a rare combination of highly coveted qualities including humility. She made everything easy from the very beginning. Chris was always available to offer help and guide me in the right direction. I would also like to thank Dr. Matthew Peveler for being a pillar of support. I am grateful to Shail Patel and William Allen for providing suggestions backed by their experience. Finally, I would like to thank RPI students and fellow GSoC contributors to review my PRs and to make this journey even more fruitful and fulfilling, I learned something from everyone. + + +Get in touch with me at [akshatbatra25@gmail.com](mailto:akshatbatra25@gmail.com) if you have any freelance/full-time work opportunities. Working on challenging stuff is my priority. diff --git a/_docs/developer/google_summer_of_code/2022_Madhur_Jain.md b/_docs/developer/google_summer_of_code/2022_Madhur_Jain.md new file mode 100644 index 00000000..9119cf2d --- /dev/null +++ b/_docs/developer/google_summer_of_code/2022_Madhur_Jain.md @@ -0,0 +1,74 @@ +--- +title: Madhur Jain +category: Developer > Google Summer of Code 2022 +--- +## About +My Name is [Madhur Jain](https://github.com/immortalcodes). I am a Computer Science undergradute from the Indian Institute of Technology Bhilai. + +## About the Project : + +### PWA : Progressive Web APP +PWAs are great solutions to applications that want great capabilities like platform specific apps and wide reach like web apps , as it provides best of both worlds . +They are built and enhanced with modern APIs to deliver enhanced capabilities, reliability, and installability while reaching anyone, anywhere, on any device with a single codebase. + + +### Aim of the Project +The main aim of the Project was to develop a installlable PWA for the Submitty application that could be installed on any platform and offer all the functionalities (even more) that a web app has to offer. +Additionally milestones included adding the support for push notifications , offline cache]ing and betterment of frontend user experience for the various platforms. + + +### Major Work on the installation of PWA : +- [[Feature:System] Installable PWA for Submitty](https://github.com/Submitty/Submitty/pull/8121) + + +### Pull requests related to work done on UserInterface/User Experience enhancements and fixing up Bugs : +- [[Feature:TAGrading] Fixed Columns for easy grading)](https://github.com/Submitty/Submitty/pull/8173 ) +- [[Bugfix:InstructorUI] Fixed Hard Coded colors](https://github.com/Submitty/Submitty/pull/7888) +- [[Bugfix:InstructorUI] Dark mode rubric table background](https://github.com/Submitty/Submitty/pull/7964) +- [[Bugfix:InstructorUI] Fixed Textbox not displaying](https://github.com/Submitty/Submitty/pull/7994) +- [[Bugfix:InstructorUI] Fixed PDF Annotation Toolbar](https://github.com/Submitty/Submitty/pull/8000) +- [[Bugfix:InstructorUI] Fixed Edit Gradeables page](https://github.com/Submitty/Submitty/pull/7984) +- [[Bugfix:Forum] Forum Title now Display Current Thread](https://github.com/Submitty/Submitty/pull/8062) +- [[Bugfix:Forum] Fixed Settings layout in New thread](https://github.com/Submitty/Submitty/pull/8104) +- [[Bugfix:CourseMaterials] Overlapping Buttons in UI](https://github.com/Submitty/Submitty/pull/8274) + + +### Work on additional features of PWA: +This work is a good reference to the implementation of the mentioned features and was aimed at developing a prototype of what path could be followed for the best integration for these features. + +#### Work on Push Notifications : +- [Branch : pushnoti](https://github.com/Submitty/Submitty/tree/pushnoti) +##### What it does currently: +User is provided with an button to enable push notifications for the application, which upon clicking asks the user permissions for push notifications. +If user allows it , a push subscription is generated (if not generated already) using a secure public key and this subscription is routed to the port 3000 at which the backend node server is listening to requests , the backend server receives the push subscription and saves it in the main submitty database. +This node server is continuously running and it fetches the notifications that are to be send form the database , these notifications are then sent to push subciptions for the users stored in the database earlier using the web-push library. +On the frontend, these notifications are received by the user’s active service worker and upon listening to the push event it formats the information received into user readable push notifications and sends to the browser to display to the user. +##### Future Scope: +The code is currently being written using Javascript and node , much of the code could be re-written in php along with the use of pre-existing code available in the codebase in php. +A separate table could be created to manage and send push notifications which could be included with several functionalities to improve the user experience. +There are a couple of options of how push notifications could be formatted with in a service worker and could be used to show interactive push notifications. + + +#### Work on Offline caching using Workbox: +- [Branch : example_wb](https://github.com/Submitty/Submitty/tree/example_wb) +##### What has been done: +This was a basic example for how offline cache could be implemented using workbox , the following branch contains initialization and setting of the workbox: +##### Future Scope : +Decide and implement the caching strategies for various pages depending upon how often they get updated , the information on those pages etc. + + +## Overall Experience and Learnings : + +My GSoC journey at Submitty was one of the best experiences that I had as a developer and as a learner. Working on a project that is used daily by a huge number of Students and Teachers for the management of courses in college education is truly incredible. Being a college student myself I was able to resonate thoroughly with the application and that made my work and experience so lively and relatable. +On the technological front, I was able to explore and dive into a lot of awesome codes and concepts. The amount of exposure and learning throughout the development process provided me with deep insights regarding several good coding practices and methods. The best thing I gained was learning about how to plan and lay the foundation for the features you want to achieve as a developer and even more what is the best path forward with all the options and tech stacks available. +The Submitty developers' team has been awesome, they created a great environment for productive discussions and resolutions of doubts and queries. Daily meetings over Webex, suggestions, comments and discussions over Slack and Github helped a lot to improve and bring the best version of code. +I love the vision behind Opensource and being able to contribute to one such project had a great impact on me that will further motivate me to explore and contribute more to Opensource. + + + +## Acknowledgement : + +I am highly grateful to the whole Submitty Team for their constant support and help. I would like to thank [Barbara Cutler](https://github.com/bmcutler) for her crucial guidance throughout the project. I can't thank [Shail Patel](https://github.com/shailpatels) enough, for all the 1v1 guidance, help, encouragement and learnings he provided. Our discussions and interactions provided me with deep insights that go beyond the dimensions of the project. Constant help from +[Chris](https://github.com/cjreed121) and [William](https://github.com/williamjallen) helped me move forward with my project. +I am also grateful to the RPI students and fellow GSoC contributors who worked on Submitty during the summers and helped in reviewing and discussing my contributions. +Lastly, I would like to thank Google for organising the Google Summer of Code program that helps foster the culture of Opensource within the developers. diff --git a/_docs/developer/google_summer_of_code/2022_Poorna_Gunathilaka.md b/_docs/developer/google_summer_of_code/2022_Poorna_Gunathilaka.md new file mode 100644 index 00000000..c08b8fa2 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2022_Poorna_Gunathilaka.md @@ -0,0 +1,53 @@ +--- +title: Poorna Gunathilaka +category: Developer > Google Summer of Code 2022 +--- + +My Google Summer of Code project with Submitty is to revamp the `count` static analysis tool. +`count` tool is used in Submitty to verify that the student submissions contains specific language features. The existing `count` tool did not support some new python features and was not working correctly for C/C++ programs. + +The new `count` tool implementation is based on [tree-sitter](https://tree-sitter.github.io/tree-sitter/) and uses an Abstract Syntax Tree generated from `tree-sitter`. +Implementation of this new tool is carried out in the [AnalysisToolsTS](https://github.com/Submitty/AnalysisToolsTS) repository. + +Initially there was an implementation of `count` tool with basic functionality using `tree-sitter` Javascript bindings. I first tried to integrate this implementation to the Submitty autograding commands. Unfortunately this was not working due to system call filtering which was preventing a nodeJS program from running in autograding. + +Next I tried to implement `count` tool using the `tree-sitter` C-API. I first verified that it was possible to use the C-API implementation with Submitty autograding without running into runtime limits or system call filtering. I initially added support for counting C, C++ and Python. Later I added support for Java. + +While working on this project I got to work with C, C++, bash and python. I wrote few github actions which does C++ static analysis of the source code, Shell checks and run tests. + +Documentation for the new command is added to the website. + +I also got the chance to work with docker container. Submitty autograding can be run in a docker container. The dockerfiles relevant to these docker containers had to be updated to the include the new `count` command. To keep the size of the docker images minimal it was decided only to include the binaries in docker images. Therefore I created a new github action in the AnalysisToolsTS repo which builds binaries from the source code when a new release is made. These binaries were then used in the docker images. + +#### Main Pull requests in AnalysisToolsTS: +- [[Feature:Autograding] tree-sitter c-api](https://github.com/Submitty/AnalysisToolsTS/pull/2) +- [[Feature:Autograding] Add Java counting](https://github.com/Submitty/AnalysisToolsTS/pull/9) +- [[Feature:Developer] Build binaries on release](https://github.com/Submitty/AnalysisToolsTS/pull/6) + + +## Other contributions + +While working on the `count` command, I also worked on autograding features and bugfixes in Submitty main repository. + + +#### BugFixes +- [[Bugfix:Autograding] Success, information messages not shown](https://github.com/Submitty/Submitty/pull/8264) +- [[Bugfix:Autograding] Random input-output build](https://github.com/Submitty/Submitty/pull/8185) +- [[Bugfix:InstructorUI] Peer graders grading themselves](https://github.com/Submitty/Submitty/pull/7983) +- [[Bugfix:TAGrading] Nav buttons not entirely clickable](https://github.com/Submitty/Submitty/pull/7963) +- [[Bugfix:TAGrading] Fix broken Home link in TA grading](https://github.com/Submitty/Submitty/pull/7800) +- [[Bugfix:TAGrading] Fix turning off random order](https://github.com/Submitty/Submitty/pull/7799) +- [[Bugfix:Submission] Fix bad breadcrumb link for peer grading](https://github.com/Submitty/Submitty/pull/7783) +- [[Bugfix:CourseMaterials] Restrict course material for no section](https://github.com/Submitty/Submitty/pull/7770) + +#### Features +- [[Feature:Autograding] Tolerance check in diff validator](https://github.com/Submitty/Submitty/pull/8251) +- [[Feature:Autograding] Environment variables in config.json](https://github.com/Submitty/Submitty/pull/8086) +- [[Feature:Autograding] Autograding command json file](https://github.com/Submitty/Submitty/pull/8046) +- [[Feature:Autograding] Add comment counting](https://github.com/Submitty/Submitty/pull/8035) + +I also got the chance to review Pull requests. This was my first experience with reviewing pull requests + +## Acknowledgement: + +I am grateful for the guidance and advices received from my mentors Barbara Cutler and William Allen. I always got quick responses on my queries and I got the resources and advices I needed to work with. I am also grateful for the RPI students and fellow GSOC-contributors who worked on Submitty during the summer. I had a wonderful time working on this project and gained valuable experience. diff --git a/_docs/developer/google_summer_of_code/2023_Cameron_Peterson.md b/_docs/developer/google_summer_of_code/2023_Cameron_Peterson.md new file mode 100644 index 00000000..fdf627db --- /dev/null +++ b/_docs/developer/google_summer_of_code/2023_Cameron_Peterson.md @@ -0,0 +1,60 @@ +--- +title: Cameron Peterson +category: Developer > Google Summer of Code 2023 +--- + +## Continuous Integration Optimization +My project for Google Summer of Code 2023 was to improve Submitty's Continuous Integration pipeline by both adding tests to increase code coverage, and improving the test time for faster feedback to developers. My first few pull requests (PRs) weren't directly related to testing, but they gave me an in-depth knowledge of the codebase, which allowed me to optimize and refactor existing tests. + +## Gradeable Creation +My first few PRs related to GSOC 2023 were focusing on adding other ways to submit assignments to Submitty. The first PR was to add support for externally created Version Control System (VCS) repositories. In doing so, I was able to get in-depth knowledge on how Submitty handled obtaining and grading homework assignments, which was helpful for later testing improvements. The second PR was adding support for subdirectories within a repository. This gave me more knowledge on how gradeables were created, and how they were handled behind the scenes. The next two PRs were quality of life changes for the two previous PRs, one giving the ability to change the subdirectory settings after the gradeable was created, and one changing the error messages that the students receive in the event of a bad submission. The last main PR that I worked on for gradeables was adding VCS gradeables to the sample course. I also updated the documentation for the features that I added. + +### Main PR's for Gradeable Creation +* [Private VCS Repos](https://github.com/Submitty/Submitty/pull/9382) +* [VCS Subdirectory Support](https://github.com/Submitty/Submitty/pull/9317) +* [Add/Remove Subdirectory After Created](https://github.com/Submitty/Submitty/pull/9423) +* [VCS Submission Error Messages](https://github.com/Submitty/Submitty/pull/9399) +* [VCS Gradeables in Sample Course](https://github.com/Submitty/Submitty/pull/6922) +* [Documentation: Update Gradeable Creation](https://github.com/Submitty/submitty.github.io/pull/519) +* [Documentation: Private VCS Repos](https://github.com/Submitty/submitty.github.io/pull/430) + +### Bugfixes for PR's +* [Fix error message on Do Not Grade](https://github.com/Submitty/Submitty/pull/9448) +* [Fix Sample Course Variables](https://github.com/Submitty/Submitty/pull/9480) +* [Fix get_vcs_info Return Value](https://github.com/Submitty/Submitty/pull/9461) + +## Continuous Integration +After finishing the PR's related to gradeables, I started working on improving the continuous integration (CI) pipeline. The first PR that got merged was an old PR that I took over, adding tests for PHP functions in the plagiarism section of Submitty. I also took over a PR to add Yamllint to the Github Actions pipeline. At this point, Submitty was using Selenium to do some end-to-end tests, and they were becoming flaky and increasingly difficult to test locally. We decided to switch from some Selenium tests, and some Cypress tests to entirely Cypress tests. I re-wrote or helped re-write multiple of the Selenium tests in Cypress, and helped write multiple tess from scratch. After all of the Selenium tests that were running in CI were changed to Cypress, I removed Selenium from the CI, and changed a couple of the tests to pass. At this point, all of the tests passed on a consistant basis, and none of them were flaky. I also did some small changes to increase the reliability of tests. + +## Main PR's for CI tests +* [Replace Forum tests](https://github.com/Submitty/Submitty/pull/9393) +* [Replace Profile tests](https://github.com/Submitty/Submitty/pull/9505) +* [Replace Sidebar tests](https://github.com/Submitty/Submitty/pull/9503) +* [Replace PDF tests](https://github.com/Submitty/Submitty/pull/9518) +* [Replace Simple Grader tests](https://github.com/Submitty/Submitty/pull/9518) +* [Replace Submission tests](https://github.com/Submitty/Submitty/pull/9406) +* [Add Gradeable edit tests](https://github.com/Submitty/Submitty/pull/9179) +* [Remove Selenium from CI](https://github.com/Submitty/Submitty/pull/9530) +* [Add Yamllint to CI](https://github.com/Submitty/Submitty/pull/8864) +* [Documentation: Remove Selenium References](https://github.com/Submitty/submitty.github.io/pull/9517) +* [Documentation: Integrate Cypress Cloud Doc](https://github.com/Submitty/submitty.github.io/pull/534) + +## Smaller PR's/bugfixes +* [Comment out Selenium Submission test](https://github.com/Submitty/Submitty/pull/9460) +* [Comment out Download in test](https://github.com/Submitty/Submitty/pull/9446) +* [Comment out Autograding Status Test](https://github.com/Submitty/Submitty/pull/9462) +* [Re-add part of Autograding Status Test](https://github.com/Submitty/Submitty/pull/9499) +* [Change login from UI to POST request](https://github.com/Submitty/Submitty/pull/9522) +* [Update DockerUI selectors](https://github.com/Submitty/Submitty/pull/9617) +* [Check for Server Error in Sidebar tests](https://github.com/Submitty/Submitty/pull/9620) +* [Remove Chromedriver setup](https://github.com/Submitty/Submitty/pull/9588) +* [Make Forum Selenium tests not run in CI](https://github.com/Submitty/Submitty/pull/9466) + +## Cypress Cloud +After the midterm evaluation, I started working on decreasing the time that the CI took to run. The first part of this was done by another contributor by splitting up Cypress, Selenium, and Integration tests to run separately but parallel. I started looking into ways to decrease the testing time, while not reducing the test coverage. In doing so I came across Cypress Cloud, and their open source license. Submitty was granted an open source license, which allowed me to change the way our CI works. Now, we record the tests to Cypress Cloud, instead of saving artifacts in Github Actions. This allows for Cypress Cloud to automatically parallelize the tests between four machines, reducing the test time from around one hour, to averaging thirty-five minutes. + +## Cypress Cloud PR +* [Integrate Cypress Cloud](https://github.com/Submitty/Submitty/pull/9517) + +## Final Overview +In working with Submitty and other contributors, I have learned a significant amount about open source contributions. (Almost) Every weekday, Barb Cutler lead an hour long meeting to discuss progress and support requests with GSOC and Submitty contributors. William Allen and I met once a week to discuss progress, and figure out new projects. Thanks to them, and all of the other contributors I was able to improve Submitty's testing infrastructure, by both increasing the code coverage and decreasing test time. The hardest part was working with slow internet, when switching back and forth between Git branches and remaking a VM took around twenty minutes each time. This caused me to be unable to review other contributors PRs as effectively, only being able to review the code on Github until it looked good, then sacrificing the time to switch to the branch to test it locally. The most rewarding part was watching the test time decrease from over an hour, to averaging thirty-five minutes. \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/2023_Musaab_Imran.md b/_docs/developer/google_summer_of_code/2023_Musaab_Imran.md new file mode 100644 index 00000000..66451edf --- /dev/null +++ b/_docs/developer/google_summer_of_code/2023_Musaab_Imran.md @@ -0,0 +1,163 @@ +--- +title: Musaab Imran +category: Developer > Google Summer of Code 2023 +--- + +## 🛡️ Website Security and Penetration Testing +The security of the Submitty website is of paramount importance due to its direct impact on student grades and academic integrity. Even a single vulnerability can lead to unfair academic advantages and legal complications concerning student data protection. Therefore, this project aimed to contribute to the assurance of proper access control, authorization mechanisms, and robust code that align with the high security standards expected from educational platforms like Submitty. + +You can find all my merged PRs in this link. + +--- +## 🎯 Project Scope +The primary goal of this project was to conduct an extensive penetration testing campaign to identify and remediate potential vulnerabilities in the Submitty website. The scope of the project encompassed a wide array of attacks, spanning from common web vulnerabilities to more advanced exploitation techniques. The ultimate aim was to fortify the security posture of Submitty and bolster its protection against malicious attacks. + +--- +## 💡 Penetration Testing Highlights +Throughout the Google Summer of Code program, I engaged in a full-fledged penetration testing lifecycle. I meticulously tested the Submitty website for vulnerabilities and potential security gaps. + +###### ☠️ Attacks +The following list presents an overview of the attacks that were tested: +1. Cross-Site Scripting (XSS) +2. SQL Injection +3. Cross-Site Request Forgery (CSRF) +4. Remote File Inclusion (RFI) +5. Local File Inclusion (LFI) +6. Server-Side Request Forgery (SSRF) +7. Clickjacking +8. Directory Traversal +9. XML External Entity (XXE) Injection +10. Zip Bomb +11. Command Injection +12. Path Traversal +13. Session Hijacking +14. Remote Code Execution (RCE) +15. Open Redirects +16. Authentication Bypass +17. XML Injection +18. JSON Injection +19. DOM-based XSS +20. HTML Injection +21. Web Shell Upload +22. XML Quadratic Blowup +23. Reflected File Download +24. Null Byte Injection +25. File Upload + +###### 🛠️ Tools +To achieve a comprehensive security assessment, I used various security tools, including but not limited to: + +1. Nessus +2. Nikto +3. SQLMap +4. Burp Suite +5. Nmap +6. Wireshark +7. Metasploit +8. OWASP ZAP (Zed Attack Proxy) + +--- +## 🔎 Static Code Analysis +In addition to dynamic testing, I performed static code analysis using prominent vulnerability scanning tools such as: + +1. CodeQL Analysis +2. Snyk Security +3. DevSkim +4. Codacy Security Scan +5. EthicalCheck + +--- +## 🔐 Security PRs +This section contains pull requests related to security enhancements, fixes, and updates. + +#### Cache Control +Implemented Cache-Control header to ensure proper resource caching behavior. This prevents intermediaries from caching the resource, reducing the risk of serving outdated content. + +🔺[PR #9693](https://github.com/Submitty/Submitty/pull/9693) + +#### Content Type Options +Content-Type-Options header stops pages from loading during content-sniffing attacks, significantly reducing security risks by preventing incorrect MIME type interpretation. + +🔺[PR #9694](https://github.com/Submitty/Submitty/pull/9694) + +#### Content Security Policy +Implemented Content-Security-Policy header which prevents external iframe embedding, bolstering security by mitigating clickjacking threats. + +🔺[PR #9695](https://github.com/Submitty/Submitty/pull/9695) + + +#### Adding CORS Security Headers +Implemented CORS security headers to prevent cross-origin attacks, enhancing web security by preventing potentially unsafe cross-origin interactions, safeguarding against credential leakage and minimizing data exposure risks. + +🔺[PR #9771](https://github.com/Submitty/Submitty/pull/9771) + + +#### Referrer Policy Header +Implemented Referrer-Policy header to prevent the leakage of sensitive information, reducing the risk of information disclosure attacks. + +🔺[PR #9772](https://github.com/Submitty/Submitty/pull/9772) + + +#### Whitelisting MIME Types +Whitelisted MIME types to prevent the execution of potentially dangerous file types. This reduces the risk of remote code execution and other malicious attacks. Only the allowed MIME types can be uploaded to the server. + +🔺[PR #10003](https://github.com/Submitty/Submitty/pull/10003) + +--- +## 👾 Bugfix PRs +In this category, you'll find pull requests aimed at resolving various bugs. + +#### Registration Section Input Validation +🔹[PR #9582](https://github.com/Submitty/Submitty/pull/9582) + +#### Student Name in Blind Grading +🔹[PR #9644](https://github.com/Submitty/Submitty/pull/9644) + +#### Download Files For Hidden Test Cases +🔹[PR #9678](https://github.com/Submitty/Submitty/pull/9678) + +#### Number of Late Days +🔹[PR #9691](https://github.com/Submitty/Submitty/pull/9691) + +--- +## 🎨 UI/UX PRs +This section showcases pull requests that enhance the look, feel, and overall usability of our system. + +#### Peer Grading Submission Browser +🔸[PR #9571](https://github.com/Submitty/Submitty/pull/9571) + +#### Student Photos Upload Instructions +🔸[PR #9688](https://github.com/Submitty/Submitty/pull/9688) + +#### Grade Inquiries per Grader +🔸[PR #9689](https://github.com/Submitty/Submitty/pull/9689) + +#### Course Materials to Course Staff +🔸[PR #9692](https://github.com/Submitty/Submitty/pull/9692) + +--- +## 📚 Documentation PRs +This category contains pull requests that added documentation of the Submitty. + +#### InstallationTroubleshooting for Remote Users +🔻[PR #510](https://github.com/Submitty/submitty.github.io/pull/510) + +#### Virtual Machine Snapshots +🔻[PR #521](https://github.com/Submitty/submitty.github.io/pull/521) + +#### Updating Disabled Functions List +🔻[PR #541](https://github.com/Submitty/submitty.github.io/pull/541) + +--- +## 🚩 Conclusion +The Submitty Website Security and Penetration Testing project was an exciting and rewarding journey. By executing a wide array of attacks and utilizing many security tools, I aimed to create a safer and more resilient platform for educational purposes. I am thrilled to have contributed to the enhancement of Submitty's security and to have strengthened its overall security posture. + +For any inquiries, feedback, or additional information, please feel free to contact me at musaabimran2001@gmail.com. + +--- +## 🤝 Acknowledgment +I extend my heartfelt gratitude to the Submitty team for their unwavering support throughout the Google Summer of Code program. My sincere thanks to mentors Dr. Barb Cutler and Chris Reed for their invaluable guidance, which significantly enriched my learning experience. Their expertise and insights were pivotal in shaping my growth, and I eagerly anticipate contributing to Submitty in the future. + +Sincerely, + +Musaab Imran diff --git a/_docs/developer/google_summer_of_code/2023_Saumya_Borwankar.md b/_docs/developer/google_summer_of_code/2023_Saumya_Borwankar.md new file mode 100644 index 00000000..c0246281 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2023_Saumya_Borwankar.md @@ -0,0 +1,54 @@ +--- +title: Saumya Borwankar +category: Developer > Google Summer of Code 2023 +--- + +My project for the Google Summer of Code 2023 was to improve already exisiting docker pipelines and streamline them to better support previous assignments and tutorials. I was also responsible to update all the previous dockerfiles and autograding examples to support docker execution. Docker provides an isolated environment for execution of student submitted code ensuring security and constraints. This is an important need for Submitty to ensure no malicious code submitted by students affect the underlying hardware or software. + +## Submitty and dockers + +Submitty uses config files to build gradeables and I had to familiarize how these config files are used to build gradeables. I was responsible for extensive testing and recreating autograding examples and convert the already existing config files to use docker instead of running on a bare metal machine. I got a chance to interact with the Submitty WebUI to build these gradeables and test out all the autograding examples. + +Submitty also has a dockerhub account where they store all their docker images. An admin has to manually push docker images to this dockerhub account when a new docker image is created by an instructor. I was responsible for automating this pipeline and building a github action workflow for automatic build and pushing of dockerfile to submitty's dockerhub account. Any new dockerfile that was pushed to the Dockerfile repository was automatically build and pushed to the dockerhub account with customizable tags using a config file present in the repository. + +I also had the opportunity to streamline and work on the Dockerfiles repo maintained by Submitty that holds all their dockerfiles and docker related information. I rebuilt all the dockerfiles that were outdated and broken. I was also responsible to setup a new standard on how the dockerfiles in the repository were stored and handled which led to a more structured repository which in turn would help new contributors to maintain the repository and contribute. + +Overall, my journey during this program allowed me to bolster Submitty's Docker pipelines, facilitating secure and efficient code execution for student submissions, while also fostering a more organized and collaborative repository ecosystem. + +### Pull Requests in Submitty + +- [Bugfix: Broken links](https://github.com/Submitty/Submitty/pull/9319) +- [Fix button texts](https://github.com/Submitty/Submitty/pull/9019) +- [Remove logging errors](https://github.com/Submitty/Submitty/pull/8952) +- [Replace outdated methods](https://github.com/Submitty/Submitty/pull/8856) +- [Update sort type for "Autograding" field](https://github.com/Submitty/Submitty/pull/8855) +- [Better error debugging for errors](https://github.com/Submitty/Submitty/pull/9710) +- [Dockerize existing autograding examples](https://github.com/Submitty/Submitty/pull/9445) + +### Pull Requests in Dockerfiles + +- [Broken Sym links](https://github.com/Submitty/DockerImages/pull/30) +- [Matrix based github action for docker hub](https://github.com/Submitty/DockerImages/pull/19) +- [Fixing broken Dockerfiles](https://github.com/Submitty/DockerImages/pull/20) +- [Cleanup and Structure Dockerfile repository](https://github.com/Submitty/DockerImages/pull/21) +- [Updating latest.json](https://github.com/Submitty/DockerImages/pull/22) +- [Structure change for verilog](https://github.com/Submitty/DockerImages/pull/24) +- [Bugfix: Variable name](https://github.com/Submitty/DockerImages/pull/25) +- [Bugfix: Rerun workflow trigger](https://github.com/Submitty/DockerImages/pull/26) +- [Bugfix: Seperate verilog rerun](https://github.com/Submitty/DockerImages/pull/27) + +## Pull Requests in submitty.github.io + +- [Removed duplicate installation steps](https://github.com/Submitty/submitty.github.io/pull/501) + +While working with Submitty I got to work with bash, python, PHP and dockerfiles. I also got the chance to review Pull requests. This was my first experience with reviewing pull requests. + +## Acknowledgement: + +I deeply appreciate the invaluable guidance and advice generously provided by my mentors, Barbara Cutler and Chris Reed. Their prompt responses to my queries and their consistent provision of essential resources have been instrumental to my progress. Expressing my gratitude extends to the dedicated RPI students and fellow GSOC-contributors who collaborated on enhancing Submitty throughout the summer. The journey of working on this project has been truly enriching, allowing me to acquire meaningful experience. I wish to continue to contribute to Submitty in the future. + +For any inquiries, feedback, or additional information, please feel free to contact me at **[sborwankar@hawk.iit.edu](mailto:sborwankar@hawk.iit.edu)**. + +Thank you, + +**[Saumya Borwankar](https://www.linkedin.com/in/saumyaborwankar)**. diff --git a/_docs/developer/google_summer_of_code/2024_Nithish_Reddy_Banda.md b/_docs/developer/google_summer_of_code/2024_Nithish_Reddy_Banda.md new file mode 100644 index 00000000..278d92ae --- /dev/null +++ b/_docs/developer/google_summer_of_code/2024_Nithish_Reddy_Banda.md @@ -0,0 +1,53 @@ +--- +title: Nithish Reddy Banda +category: Developer > Google Summer of Code 2024 +--- + +My project for Google Summer of Code 2024 focused on extending and generalizing Submitty's autograding features to support multi-language compatibility and ensure seamless execution within Docker environment. This enhancement is vital for maintaining system stability under load on the primary machine. In addition to this core development, I also significantly improved the visual design of the diff viewer for autograding results, enhancing the user experience. Furthermore, I strengthened security measures in the peer grading process and implemented features aimed at reducing potential complexity for peer graders. + +I am [Nithish Reddy Banda](https://github.com/GO-viper7), Computer Science graduate from [Indian Institute of Information Technology, Sri City](https://www.iiits.ac.in/). + +This project was mentored by [Barbara Cutler](https://github.com/bmcutler). + +## Autograding and Peer Grading in Submitty + +Submitty uses configuration files to build gradeables, so I first had to familiarize myself with how these files are utilized. Some autograding features use these config files to validate submitted outputs against those provided by instructors. I spent a considerable amount of time understanding this workflow and eventually expanded the usage of instructor solutions to C++ by introducing new specifications in the config files, generalizing the process for other programming languages as well. + +Submitty also employs worker threads to ship files to secure environments for autograding, such as Jailed sandboxes and Docker container networks. I became familiar with these distributed workflows and utilized these threads to parallelly build the gradeables. + +Peer grading is another area where I made significant contributions. I implemented functionality that enables instructors to manage the visibility of panels for peer graders, thereby minimizing ambiguity. Additionally, I fixed a major security flaw that allowed peer graders to grade their own team members. + +Beyond these tasks, I contributed to numerous bug fixes, including issues within the calendar, gradeable dates, team name constraints and etc. The contributions I made this summer greatly enhanced my understanding of Object-Oriented concepts, database migrations, ORMs, Docker containers, non-repeatable and modular code, security and concurrency concepts, and most importantly, team collaboration. + +### Pull Requests in Autograding + +- [Instructor Solution written in C++](https://github.com/Submitty/Submitty/pull/10608) +- [Distinguish Insertion/Deletion results](https://github.com/Submitty/Submitty/pull/10752) +- [Add Missing examples to Development](https://github.com/Submitty/Submitty/pull/10535) + +### Pull Requests in Peer Grading + +- [Grading panel visibility to Peer Graders](https://github.com/Submitty/Submitty/pull/10193) +- [Unassign graders to grade team members](https://github.com/Submitty/Submitty/pull/10178) + +### Bugfixes and Refactors + +- [Change of constraints in team name](https://github.com/Submitty/Submitty/pull/10111) +- [Accessing future gradeables in calendar](https://github.com/Submitty/Submitty/pull/10240) +- [Due date validation for isStudentSubmit](https://github.com/Submitty/Submitty/pull/10264) +- [Rendering Team IDs for Graders](https://github.com/Submitty/Submitty/pull/10266) +- [Redirect out of submission if no team](https://github.com/Submitty/Submitty/pull/10356) +- [Use of data- selector instead of class's](https://github.com/Submitty/Submitty/pull/10236) + +### Pull Request in Localization + +- [Complete French translation for Profile](https://github.com/Submitty/Localization/pull/16) + +### Acknowledgements: + +I am incredibly grateful for the invaluable support and insights offered by my mentor, Barbara Cutler and fellow contributors from RCOS. Their swift responses to my questions and their consistent supply of vital resources have significantly contributed to my progress. I really enjoyed our meetings, especially the demos where everyone contributes their thoughts on designing features. I also want to acknowledge the hard work of the dedicated RPI students and fellow GSoC contributors who worked alongside me to improve Submitty over the summer. This project has been a deeply rewarding experience, providing me with valuable skills and knowledge. I look forward to continuing my contributions to Submitty in the future. + +For any questions, feedback, or further information, don't hesitate to reach out to me at **[nithishbanda2021@gmail.com](mailto:nithishbanda2021@gmail.com)**. + +Thank you, +**[Nithish Reddy Banda](https://www.linkedin.com/in/nithish-reddy-goviper/)**. \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/2024_Rahul_Vishwakarma.md b/_docs/developer/google_summer_of_code/2024_Rahul_Vishwakarma.md new file mode 100644 index 00000000..d895916b --- /dev/null +++ b/_docs/developer/google_summer_of_code/2024_Rahul_Vishwakarma.md @@ -0,0 +1,58 @@ +--- +title: Rahul Vishwakarma +category: Developer > Google Summer of Code 2024 +--- + +## About Submitty +Submitty is an open source course management, assignment submission, exam and grading system from the Rensselaer Center for Open Source Software (RCOS), Department of Computer Science at Rensselaer Polytechnic Institute. + +## About My GSoC project +The primary goals for this project include the expansion of our automated testing of the TA Grading pages and to patch bugs uncovered by this improved testing. The project may be expanded in scope to additionally propose and execute small or modest user interface revisions that enhance the TA experience, especially for graders who are new to the interface and grading process. + +## About My Work +My first PR in Submitty is regarding the grade inquiry test which got closed after I raised pr for it because someone was already working on it, later I took the pr because the guy didn’t complete the work. So, I aim to expand cypress testing for the TA Grading Section. And try to fix the bugs and issues that I get during the testing and some other issues too. So I have done a lot of testing in Submitty as a GSoC contributor with the javascript and cypress tool till now. + +Most of the time, i spent on the Rubric Grading Interface for adding test to it and fixes the some bugs by the way Rubric Grading Interface is customizable layout with a number of essential and helpful panels. Depending on the assignment configuration and manual grading tasks, the grader can customize the display, arrangement, and dimensions of these panels([more info](https://submitty.org/grader/rubric_grading/index#customizable-grading-panels)). Sections which does not had much tests like TA Grading, Disscussion Forum, Notebook Section, Peer Grading, File and Directory section later i added possible test for it. + + +## Visual Regression Testing +For the visual testing with Cypress, we used the [cypress-image-diff](https://github.com/haim-io/cypress-image-diff) plugins it uses pixelmatch for the comparison of images based on what we provide the image in the baseline folder, [pixelmatch](https://github.com/mapbox/pixelmatch) is the simplest and fastest JavaScript pixel-level image comparison library and it relies on the cypress for taking the screenshots. +I used the visual regression testing tool for testing the Markdowns  and  Mermaid  flowcharts. + +### Main PR's +* [Add tests for grade override](https://github.com/Submitty/Submitty/pull/10697) +* [Download Zip File](https://github.com/Submitty/Submitty/pull/10694) +* [Added Test for Grading Details UI](https://github.com/Submitty/Submitty/pull/10686) +* [TA Rubric Attachments Access](https://github.com/Submitty/Submitty/pull/10371) +* [Added Test for Peer Grading](https://github.com/Submitty/Submitty/pull/10560) +* [Selenium to Cypress office_hours_queue](https://github.com/Submitty/Submitty/pull/10357) +* [Added Test for Discussion Post Panel](https://github.com/Submitty/Submitty/pull/10536) +* [Forum Image attachment](https://github.com/Submitty/Submitty/pull/10348) +* [Added remaining test button in pdf](https://github.com/Submitty/Submitty/pull/10532) +* [Cycling Grader View](https://github.com/Submitty/Submitty/pull/10333) +* [Testing TA Grading hotkeys](https://github.com/Submitty/Submitty/pull/10504) +* [Notebook Builder And Panel](https://github.com/Submitty/Submitty/pull/10766) +* [Rubric Grading Interface](https://github.com/Submitty/Submitty/pull/10755) + + +### Smaller / Bugfixes PR's +* [Fixed title and Shortcut for Notebook](https://github.com/Submitty/Submitty/pull/10511) +* [Uncaught Reference Error - self_grading undefined](https://github.com/Submitty/Submitty/pull/10557) +* [Issue Student and Grader should be Different](https://github.com/Submitty/Submitty/pull/10684) +* [TypeError NUM_MARKDOWN variable](https://github.com/Submitty/Submitty/pull/10725) +* [Uncaught SyntaxError Notebook](https://github.com/Submitty/Submitty/pull/10787) + +### Other PR's +* [Cypress grade inquiries test](https://github.com/Submitty/Submitty/pull/10235) +* [Add cypress test for Rainbow Grading](https://github.com/Submitty/Submitty/pull/10255) +* [Implement Image Diff For Markdown](https://github.com/Submitty/Submitty/pull/10260) + + +## Overview +So, this has been the best experience of my life. Whenever I will think about open source Submitty will come first. I learned a lot of things from this organization technical and non-technical. I would like to thank Cameron, Barb, William, and other fellow GSoC and RPI contributors for supporting me. Every day(Monday to Friday) Barb leads an hour-long meeting to discuss the progress of GSoC and RPI contributors. Every Thursday, One-on-One interaction with Cameron through Zoom Call to discuss progress, new ideas, and issues regarding opened pr. At the last, it was great experience for me to working in a such a big team i never had work with such a big team. + +For any inquiries, please feel free to contact me at [rahulvs2809@gmail.com](mailto:rahulvs2809@gmail.com) + +Thank You Submitty, + +[Rahul Vishwakarma](https://www.linkedin.com/in/rahul-vishwakarma-553874256/) \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/2024_Sahil_Suman.md b/_docs/developer/google_summer_of_code/2024_Sahil_Suman.md new file mode 100644 index 00000000..76f5d504 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2024_Sahil_Suman.md @@ -0,0 +1,61 @@ +--- +title: Sahil Suman +category: Developer > Google Summer of Code 2024 +--- + +# GSoC Final Submission Review: Streamlining the Notebook Builder UI for Automated Grading + +Participating in the Submitty project during GSoC has been a transformative experience, offering a deep dive into software development, communication with mentors, and hands-on problem-solving. My project focused on enhancing the Notebook Builder, a user interface that allows instructors to create interactive notebooks. These notebooks can be used as tutorial teaching materials or web-based exams, supporting basic markdown text formatting and various types of student input, such as multiple choice, short answers, and syntax-highlighted code boxes. + +Throughout this project, I raised several pull requests (PRs), each contributing to the functionality and usability of the Notebook Builder: + +## PRs Done Before GSoC + +* **[Bugfix: Submission] Added Note to Absence Extension** + [PR #10044](https://github.com/Submitty/Submitty/pull/10044) + I addressed an issue where the text for excused absence extensions needed clearer communication in the student view within rainbow grades. + +* **[Bugfix: Instructor UI] Upload Validation Error** + [PR #10048](https://github.com/Submitty/Submitty/pull/10048) + This PR introduced a validation error for instructors attempting to upload PDFs with incorrect page counts. Instead of adding a PHP dependency, I utilized a Python daemon worker, which already had the necessary dependencies installed, streamlining the solution. + +* **[Feature: Submission] Hide Accessibility Text for Disabled** + [PR #10649](https://github.com/Submitty/Submitty/pull/10649) + This feature focused on hiding accessibility help text in CodeMirror when code boxes are disabled, as the text was causing confusion in these scenarios. + +* **[Feature: Instructor UI] Course Material Tracking** + [PR #10650](https://github.com/Submitty/Submitty/pull/10650) + I added database migration to support course material tracking. Given Submitty's unique DB migration system, this required extensive testing and careful implementation to ensure reliability. + +* **[Bugfix: Submission] Moved Text Outside the Label Tag** + [PR #10040](https://github.com/Submitty/Submitty/pull/10040) + This PR fixed a bug where a warning message appeared incorrectly when the "hide from students" option was selected. I adjusted the label structure to resolve the issue. + +## PRs Done During GSoC + +* **[UI/UX: Submission] Notebook Button Styling** + [PR #10768](https://github.com/Submitty/Submitty/pull/10768) + I addressed several styling issues, ensuring the notebook buttons adhered to the standard website color guide, improving the overall UI consistency. + +* **[Documentation: Developer] Update Advanced Setup Guideline** + [PR #606](https://github.com/Submitty/submitty.github.io/pull/606) + While setting up Submitty locally, I identified areas for improvement in the setup guidelines and added screenshots and instructions to enhance the developer experience. + +* **[UI/UX: TAGrading] Notebook Preview Button** + [PR #10788](https://github.com/Submitty/Submitty/pull/10788) + This PR introduces a preview button in the Notebook Builder section, allowing users to see how the notebook will look on the student end. + +* **[Feature: Submission] Autosave on Notebook Gradeable** + [PR #10875](https://github.com/Submitty/Submitty/pull/10875) + This PR introduces an autosave feature for Notebook. Now, whenever any option is changed in the Notebook Grading interface, the system will automatically save the changes to the server. This enhancement aims to prevent data loss and improve the overall user experience by ensuring that no changes are inadvertently lost. + +* **[Bugfix: TAGrading] Improve Date Validation** + [PR #10876](https://github.com/Submitty/Submitty/pull/10876) + This pull request introduces an additional try-catch block to handle errors more effectively. Instead of displaying the frog error page, the error will now be caught and thrown appropriately. + +## Acknowledgements + +I am deeply grateful to [Barbara Cutler](https://github.com/bmcutler) and [William Allen](https://github.com/williamjallen) for their invaluable support throughout this project. Barbara provided crucial insights into the project's broader scope, while William's regular meetups were instrumental in guiding me through PHP debugging and best practices, especially as a newcomer to the language. + +Thank you, +[Sahil Suman](https://github.com/sahilsuman933) \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/2024_Sophia_Oliinik.md b/_docs/developer/google_summer_of_code/2024_Sophia_Oliinik.md new file mode 100644 index 00000000..c87da844 --- /dev/null +++ b/_docs/developer/google_summer_of_code/2024_Sophia_Oliinik.md @@ -0,0 +1,63 @@ +--- +title: Sophia Oliinik +category: Developer > Google Summer of Code 2024 +--- + +## Overview of project: +Through this summer, I worked on my 2024 Google Summer of Code (GSoC) project titled "Enhancing User Interface for Viewing Grades." Initially, the project aimed to improve the presentation of Rainbow Grades. However, I also wanted to incorporate and update visual representations of statistics related to homework. It was decided that I should pivot slightly towards developing a gradeable-specific statistics page and bring more updates to it. As a result, I was able to enhance the user interface design for both Rainbow Grades and the statistics page for gradeables throughout the summer. + + +## Outside of programming +In the initial weeks, I focused on understanding the Submitty codebase and the system's structure. Submitty has implemented an effective system for continuous integration and check-ins for summer contributors, facilitated by our daily meetings. These meetings provided an excellent opportunity to showcase work, receive second opinions, ask questions, and maintain accountability. Additionally, the meetings included demonstrations of our work and feedback from the team, which I utilized for a couple of my projects. This process was invaluable for identifying what worked and what needed improvement. Throughout the summer, I also received feedback from my mentor via video calls and messaging. These discussions addressed barriers I encountered and provided status updates, which were instrumental in my progress and learning while working on Submitty. +Another aspect of this summer included writing issues on where Submitty can be improved. Below are the issues I wrote this summer: +- [#10864](https://github.com/Submitty/Submitty/issues/10864) Manual Grading Histogram: fix standard deviation +- [#10877](https://github.com/Submitty/Submitty/issues/10877) Refactor for grading statistics/histogram pages + + +## Pull Request work: +Below are the pull requests I worked on this summer. The primary focus areas included the user interface for Rainbow Grades and the presentation of instructor grading data. These links encompass documentation pull requests, a pull request to the Submitty repository, and pull requests to the Rainbow Grades repository. + +- [#77](https://github.com/Submitty/RainbowGrades/pull/77) [Feature:RainbowGrades] Adding hover text to Rainbow Grades bad status cells + * This was one of the first additions I brought to Submitty. It added a feature to the Rainbow Grades gradebook page that implemented a hover text box for students that had a "bad status" on a homework. This brings more attention that the student can look into why they have a bad status on the assignment, and it brings convenience for instructors in their larger gradebooks to see who has a bad status and on what assignment with just hovering their mouse over the cell. + +- [#81](https://github.com/Submitty/RainbowGrades/pull/81) [Feature:RainbowGrades] Adding link to gradeable title + * This pull request is a work in progress. This is another implementation in the Rainbow Grades repository, I added a feature to the Rainbow Grades gradebook page that inputs a link in the gradeable titles. This is a feature that will bring convenience to students when they are viewing their Rainbow Grades grade report. Now, when the student sees their grade and wants to see the details of they they recieved that grade, they can click on the title on the grade report, and they are taken to that page. + +- [#10687](https://github.com/Submitty/Submitty/pull/10687) [Feature:TAGrading] Manual Grading Histogram + * The statistics page had tabs and data about total scores, autograding scores, and component scores, but not of manual grading scores. In this pull request I added a page with a histogram of just manual grades with its data along the bottom of the histogram screen. This was a good way to learn about how data is stored. + +- [#617](https://github.com/Submitty/submitty.github.io/pull/617) [Documentation:TAGrading] Version conflict documentation + * This documentation pull request was to update information about version conflicts. TA's and instructors would encounter version conflicts when students switched their active version to one that has not been graded. I added documentation about how resolve them. + +- [#623](https://github.com/Submitty/submitty.github.io/pull/623) [Documentation:TAGrading] Updated version conflict documentation + * An addition was added that updated the process of resolving version conflicts. I added the needed instructions on how to use this new interface accordingly. + +## Bugfix Pull Requests +Both of these bugfix pull requests were done before my summer with Submitty began. It was a good way to get introduced to the process of how the Submitty organization does pull requests from branches, and the format of titling and describing the pull request. Here I updated a broken URL, and updated some spelling errors that a linter caught. +- [#10426](https://github.com/Submitty/Submitty/pull/10426) update rainbowgrades url +- [#10427](https://github.com/Submitty/Submitty/pull/10427) fix some spelling errors + +## Pull Requests Reviewed +Having this review process this summer taught me a lot as a new contributor to Submitty. In the beginning of the summer, I was able to review a few pull requests where I learned what the process looked like for contributors, the system and syntax Submitty used, and the new additions that other contributors were adding. Below is a list of the pull requests that I reviewed and tested through the summer: +- [#10519](https://github.com/Submitty/Submitty/pull/10518) final grade gui configuration +- [#10615](https://github.com/Submitty/Submitty/pull/10615) markdown buttons exceeding width +- [#10635](https://github.com/Submitty/Submitty/pull/10635) add a clear conflict button +- [#10653](https://github.com/Submitty/Submitty/pull/10653) add manual grade to display +- [#10665](https://github.com/Submitty/Submitty/pull/10665) separate manual and gui customization +- [#10679](https://github.com/Submitty/Submitty/pull/10679) clear version conflicts with save +- [#10750](https://github.com/Submitty/Submitty/pull/10750) base_url for rainbowgrades +- [#10741](https://github.com/Submitty/Submitty/pull/10741) display memory/runtime in stats page +- [#10763](https://github.com/Submitty/Submitty/pull/10763) add gradeable percents to GUI +- [#10765](https://github.com/Submitty/Submitty/pull/10765) add ClampGradeablesInBucket +- [#10840](https://github.com/Submitty/Submitty/pull/10840) add term and course +- [#56](https://github.com/Submitty/RainbowGrades/pull/56) display rainbowgrades version +- [#10763](https://github.com/Submitty/Submitty/pull/10763) add gradeable percents to GUI +- [#10859](https://github.com/Submitty/Submitty/pull/10859) add performance warnings to display + + + + +## Acknowledgments: +I am very grateful for the opportunity to work with Submitty this summer. Throughout these weeks, I experienced significant growth as a programmer, team member, and mentee. The daily meetings were immensely helpful in learning how to communicate my progress and provided a supportive environment for asking questions. These interactions greatly contributed to my professional development. +Working directly with the codebase was also a crucial aspect of my growth this summer. I dedicated time to understanding the existing code and considered how to implement necessary changes consistently. Halfway through the summer, I pivoted the focus of my project, which taught me to be adaptable and explore new areas of Submitty that I was not previously familiar with. +The pull request review process was another valuable learning experience, allowing me to identify strengths and areas for improvement in my code. Additionally, reviewing other contributors' pull requests provided insights into their approaches and the processes they followed to enhance the system. I want to extend my gratitude to Barb Cutler, Jaeseok Kang, Cameron Peterson, and Preston Carman for their mentorship throughout my summer with Submitty. \ No newline at end of file diff --git a/_docs/developer/google_summer_of_code/GSoC_application.md b/_docs/developer/google_summer_of_code/GSoC_application.md new file mode 100644 index 00000000..b2f8efbc --- /dev/null +++ b/_docs/developer/google_summer_of_code/GSoC_application.md @@ -0,0 +1,95 @@ +--- +title: GSoC Application +category: Developer > Google Summer of Code +--- + +## How to Apply to Submitty for Google Summer of Code 20XX + +1. Read the GSOC information for contributors to confirm your eligibility: + + * [https://summerofcode.withgoogle.com/](https://summerofcode.withgoogle.com/) + + * [https://developers.google.com/open-source/gsoc/faq#what_are_the_eligibility_requirements_for_participation](https://developers.google.com/open-source/gsoc/faq#what_are_the_eligibility_requirements_for_participation) + +2. Read our [Suggestions for New Developers](/developer). + +3. Follow the developer instructions to + [install the Submitty system](/developer/getting_started/vm_install_using_vagrant) + in a virtual machine on your computer. + +4. Review our project ideas list: + [https://submitty.org/developer/getting_started/project_ideas](/developer/getting_started/project_ideas) + +5. Join our Zulip server to ask questions and meet other new developers: + [https://submitty.org/contact](/contact) + + Ask specific technical questions about the Submitty system and open + issues and help answer technical questions from other new developers if + you think you can help. Your engagement in the community discussion + during the application period (both asking and answering questions) will + + + be taken into account as we evaluate your application. + + NOTE: The Submitty mentors for Google Summer of Code are on our + Zulip server. Please communicate through the public streams and + do not direct message (DM) / private message any mentors. + Mentors will generally not respond to private messages. + + New developers should start with an issue labeled "Good First Issue". + To understand the existing functionality/bug, reproduce and test this feature on your development VM. + Inspect the relevant system files and database contents. + + + NOTE: More recent issues in the Submitty Github database tagged "Awaiting Triage" + have not yet been reviewed by the Submitty Project administrators. + These details of these bug reports and feature requests may need editing and revision + to confirm they meet with the long-term needs and goals of the Submitty project. + Before starting to work on one of these issues, we recommend you check with the + project team by creating a new discussion thread about the issue on our [Zulip server](/contact). + +7. Submit a pull request to solve an open issue. + [https://submitty.org/developer/getting_started/make_a_pull_request](/developer/getting_started/make_a_pull_request) + +8. Help test and review [open pull requests](https://github.com/Submitty/Submitty/pulls) contributed by other developers. + [https://submitty.org/developer/getting_started/review_a_pull_request](/developer/getting_started/review_a_pull_request) + + NOTE: We always have a large number of _work-in-progress_ pull + requests from both new and experienced developers. Prospective + developers with any level of experience are welcome and needed to + help review these PRs. Contributing to the review process is + beneficial to everyone. + +9. Begin work on your GSoC Project application. We recommend + prospective contributors focus on one of our suggested projects + from the [project ideas](/developer/getting_started/project_ideas) + list. Successful applicants will be able to expand and enhance the + proposed project idea with a timeline of design and implementation + milestones, and will demonstrate curiosity and motivation for the + topic. + +10. Download and complete the + [Submitty GSoC Applicant Template](/developer/google_summer_of_code/applicant_template). + + You will document your skills, relevant coursework, non-course experience, and future + career goals that qualify you to work on this project. + + The template will also ask for your approximate schedule for the + summer: start date, end date, and number of hours of work per week. + And a description of any classes, employment, or other time + commitments during that time period. + + Most importantly, you will summarize your engagement with the + Submitty project team during the application period. This includes + participation in public discussions on our [Zulip server](/contact), + authoring of new pull requests (both in progress and merged), and + detailed and constructive reviews of PRs from other developers. + + +11. The application window for Google Summer of Code closes on April XXth, 20XX at 18:00 UTC. + Please carefully read all of the program requirements. + + * [Google Summer of Code 20XX Timeline](https://developers.google.com/open-source/gsoc/timeline) + + * [https://summerofcode.withgoogle.com/](https://summerofcode.withgoogle.com/) + diff --git a/_docs/developer/google_summer_of_code/applicant_template.md b/_docs/developer/google_summer_of_code/applicant_template.md new file mode 100644 index 00000000..e752710f --- /dev/null +++ b/_docs/developer/google_summer_of_code/applicant_template.md @@ -0,0 +1,41 @@ +--- +title: Applicant Template +category: Developer > Google Summer of Code +--- + +[comment]: <> **NOTE: The 20XX Submitty GSoC Template will be available for download +[comment]: <> when Google announces the organizations accepted for Google Summer +[comment]: <> of Code 20XX.** + +To ensure that the Submitty Org Admins and Mentors have all of the +information about your ideas, project plan, and availability for +Google Summer of Code 20XX, we ask you to use the Submitty Applicant +Template. + +The template will include: + +* Your skills, relevant coursework, non-course experience, and future + career goals that qualify you to work on this project. + +* Approximate schedule for the summer: start date, end date, and + number of hours of work per week. + +* Description of any classes, employment, or other time commitments + during that time period. + +* Engagement with the Submitty project team during the application + period. This includes participation in public discussions on our + [Zulip server](/contact): asking technical questions about issues + and work-in-progress PRs, helping other prospective applicants with + installation hiccups and development problems, etc. + +* Links to all GitHub pull requests to the Submitty organization and + their current status (submitted, reviewed, revised, approved, + merged). _NOTE: significant/large pull requests take more time to + review for completeness and correctness. It's ok if your work is + not merged before the GSoC application deadline._ + +* Links to all Submitty PRs authored by other developers that you have + reviewed. _NOTE: reviews should be thoughtful and substantive. PR + reviews that simply comment "LGTM" are not as helpful._ + diff --git a/_docs/developer/google_summer_of_code/index.md b/_docs/developer/google_summer_of_code/index.md new file mode 100644 index 00000000..eb979bf2 --- /dev/null +++ b/_docs/developer/google_summer_of_code/index.md @@ -0,0 +1,93 @@ +--- +title: Google Summer of Code +category: Developer +redirect_from: + - /developer/google_summer_of_code +--- + +[comment]: <> Submitty has applied for acceptance to +[comment]: <> [Google Summer of Code (GSoC) 20XX](https://summerofcode.withgoogle.com/). +[comment]: <> Project reports from participants in previous summers are linked +[comment]: <> below. + +[comment]: <> We are thrilled to announce that Submitty has been accepted to [Google +[comment]: <> Summer of Code (GSoC) 20XX](https://summerofcode.withgoogle.com/). +[comment]: <> Project reports from participants in previous summers are linked +[comment]: <> below. + +
+ +
+ +[comment]: <> _NOTE: The organizations selected for Summer 20XX Google Summer of +[comment]: <> Code will be announced in late February. The instructions below +[comment]: <> are from 20XX and will be updated if Submitty is accepted!_ + + +[comment]: <> [Google Summer of Code Application](/developer/google_summer_of_code/GSoC_application) + + +## Google Summer of Code 2024 + +* [Streamlining the Notebook Builder UI for Automated Grading by Sahil Suman](/developer/google_summer_of_code/2024_Sahil_Suman) + +* [Automated Testing of TA Grading Pages by Rahul Vishwakarma](/developer/google_summer_of_code/2024_Rahul_Vishwakarma) + +* [Enhancing User Interface for Viewing Grades by Sophia Oliinik](/developer/google_summer_of_code/2024_Sophia_Oliinik) + +* [Docker Containers in support of Multi-Language Autograding by Nithish Reddy Banda](/developer/google_summer_of_code/2024_Nithish_Reddy_Banda) + + + +## Google Summer of Code 2023 + +* [Continuous Integration Optimization by Cameron Peterson](/developer/google_summer_of_code/2023_Cameron_Peterson) + +* [Website Security and Penetration Testing by Musaab Imran](/developer/google_summer_of_code/2023_Musaab_Imran) + +* [Docker Containers for Autograding Improvements by Saumya Borwankar](/developer/google_summer_of_code/2023_Saumya_Borwankar) + + + +## Google Summer of Code 2022 + +* [Website Security and Penetration Testing by Akshat Batra](/developer/google_summer_of_code/2022_Akshat_Batra) + +* [Progressive Web App by Madhur Jain](/developer/google_summer_of_code/2022_Madhur_Jain) + +* [Static Analysis for Autograding by Poorna Gunathilaka](/developer/google_summer_of_code/2022_Poorna_Gunathilaka) + + + +## Google Summer of Code 2020 + +* [Mobile Friendly Website by Mukul Kumar Jha](/developer/google_summer_of_code/2020_Mukul_Kumar_Jha) + +* [Live Page Updates with Websockets by Marwan Atef](/developer/google_summer_of_code/2020_Marwan_Atef) + +* [Peer Grading by Harsh Joshi](/developer/google_summer_of_code/2020_Harsh_Joshi) + + + + + +## Google Summer of Code 2019 + + +* [Continuous Integration Testing by Fon Noel](/developer/google_summer_of_code/2019_FonNoel) + +* [Automated Grading Configuration by Drumil Patel](/developer/google_summer_of_code/2019_DrumilPatel) + +* [Discussion Forum Refactor with Websockets by Anubhav Singh](/developer/google_summer_of_code/2019_AnubhavSingh) + +* [Rest API for Submitty by Xiao Han](/developer/google_summer_of_code/2019_XiaoHan) + + + +## Google Summer of Code 2018 + + +* [Discussion Forum Enhancements by Gagan Kumar](/developer/google_summer_of_code/2018_GaganKumar) + +* [Instructor Interface for Plagiarism Detection by Tushar Gurjar](/developer/google_summer_of_code/2018_TusharGurjar) + diff --git a/_docs/developer/how_to_contribute.md b/_docs/developer/how_to_contribute.md deleted file mode 100644 index ee3d15e7..00000000 --- a/_docs/developer/how_to_contribute.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: How To Contribute -category: Developer ---- - -* Each pull request (PR) should be addressing/closing an open issue. - *Usually*. - -* The PR title should be useful and descriptive (not just the issue#). - -* Titles of PR, Issues, and commits should be <= 50 characters. - *Usually*. - -* Include the string "Closes #1234" within the comment so that the - issue will be automatically closed issue when the pull request is - merged. - -* The commit message should talk about *WHAT* changed, and *WHY*. Not - *HOW*. How is the diff, and you don’t need to repeat it. - -* Comments explaining the code should be *in* the code, rather than in - the PR message or comments. - -* Including screenshots in the issue or PR message is helpful for UI - changes. - -* The comments should explain a bit about the purpose/history/overview - -- don't assume the reader knows it (or link to the issue that - explains everything). - -* Be explicit about what you want feedback on, or why you are asking - for specific reviewers. - -These guidelines drawn from: - -[https://www.atlassian.com/blog/git/written-unwritten-guide-pull-requests](https://www.atlassian.com/blog/git/written-unwritten-guide-pull-requests) - -[https://github.com/blog/1943-how-to-write-the-perfect-pull-request](https://github.com/blog/1943-how-to-write-the-perfect-pull-request) - -[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) \ No newline at end of file diff --git a/_docs/developer/index.md b/_docs/developer/index.md deleted file mode 100644 index d04eb4de..00000000 --- a/_docs/developer/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Developer ---- - -As a developer, you'll need to set up the full system on your own -computer. The easiest method is to -[run the system within a virtual machine (VM)](vm_install_using_vagrant). -Alternately, you can install the system natively on a dedicated -computer and allow outside access (which requires more steps to set up -networking, SSL/https, etc.) by following the -[complete system administrator instructions](/sysadmin). - - - -Please contribute by adding bugs or feature requests to our -[Submitty GitHub Issue Tracker](https://github.com/Submitty/Submitty/issues). - - -A list of Submitty projects (some new, some in progress): -[Project Ideas](project_ideas) - - -To contribute your software changes back to this open source project, -follow these steps: - - 1. Run the [C++ Test Suite](autograding_tests) locally. - - 2. Push your work to an appropriately named new branch on GitHub. - - 3. When your code has passed all of the [Travis CI Tests](travis_ci), then - you can make a pull request to master. - - - -### Suggestions for new developers - -* Download & install Submitty, and try it out. Read the instructor - documentation to learn the system. - -* Look through the issues list for some ideas of problems to explore. - -* Learn how to use git. - -* Learn what sections of the code are relevant for those issues (so - you’re not overwhelmed). - -* Hint: Use "git grep" to search for variables/filenames/specific - strings within the source files/directories. This can help you - locate relevant files. - -* Add & delete things to the code, re-install that portion of the - system and see what happens. - -* Use inspector or browser debugger. - -* As you read the code, make a diagram for yourself of how the system - fits together. - -* Use jsfiddle (for testing or demoing new things). - -* Keep a work diary / log: what did you plan to do today, keep track - of how long it took you to do things, difficulties, how did you - solve it, helpful reference links, and what’s your plan for - tomorrow. - -* Get familiar with vagrant. - -* Run the test suite locally. - ---- - - -We have created a new public [Slack for Submitty Developers](https://join.slack.com/t/submitty/shared_invite/enQtMzE1NzgyMzUzNzI5LWNkNjUzYmZjOWJkNzdlM2QzNTM3MGYwNmQwMzQ3NjAwODUwYjI4MTRlZDNjZTFlMTk4ZjUzN2MxNzRjNDIwZTU) - -Questions or comments can be sent to our Submitty support mailing list: -submitty-admin@googlegroups - diff --git a/_docs/developer/ms_phd_students/MS_2020_John_Hulton.md b/_docs/developer/ms_phd_students/MS_2020_John_Hulton.md new file mode 100644 index 00000000..7e6b5ca9 --- /dev/null +++ b/_docs/developer/ms_phd_students/MS_2020_John_Hulton.md @@ -0,0 +1,43 @@ +--- +title: John Hulton > MS > December 2020 +category: Developer > MS/PhD Students +redirect_from: + - /developer/MS_2020_John_Hulton +--- + +#### Abstract + +My master’s project was based on the development and improvement of a peer grading system on Submitty. Peer grading is the process in which students of a course grade other students of that course in place of an instructor or other course staff. A course can benefit from functional peer grading in two key ways. First, it lessens the workload on course staff by shifting the task of grading assignments to the students. This is essential for Massive Open Online Courses, which can have up to 30,000 students, and the. and would provide a new way for students to learn. Therefore, when developing Submitty Peer Grading, we focused on making it easy to implement for an instructor while providing ways for students to learn and interact. + +#### Peer Grading System + +My first and largest contribution was building the Peer Grading system alongside Evan Maicus and Barbara Cutler. This current version would be used as follows: + +* The instructor designates a gradable as a Peer Gradable by adding one or more Peer Components in the grading rubric. Only the Peer Components can be graded by students. Otherwise, Peer Components are identical to normal Components (they can be graded by course staff like a normal component). The instructor can also decide if the peer grading should be double-blind (student do not know who they are grading or being graded by), single-blind (students know who they are grading but not know they are being graded by) or unblind (students know who they are grading and being grading by). +[![](/images/PeerImage1.PNG)] + +* The instructor creates a set of grader-student pairings via the interface under the Peer Matrix tab in the Create/Edit Gradeable Interface. The graders on the left side are students who are assigned to grade the other students on the right side. Instructors can use the interface to randomly create pairings given the number of student each student-grader should have to grade. Instructors can also manually create, edit and delete pairs and can upload a .csv file containing student-grader pairs. +[![](/images/PeerImage2.PNG)] + +* After the assignment has been closed, student graders are able to grade the students they were assigned to view the standard grading interface. Note that the student will not be able see the name or id of the student they are grading if double-blind grading is enabled. If the Gradable contains Peer and non-Peer Components, course staff must grade the non-Peer Components as normal +[![](/images/PeerImage3.PNG)] +. An instructor can see overall peer grading progress on the stats page and the grades assigned by each peer via the new peer panel in the grading interface. +[![](/images/PeerImage4.PNG)] + +* When grades are released, students see which marks were selected by each grader (student and non-student) for each Peer Component. For each peer Component, the average score is calculated and displayed and used as the Peer Component’s score when calculating the student’s total score. If either single-blind or double-blind is enabled for the assignment, the student will not be able to determine if a certain Component grade was given by course staff or student. The student will also see each overall comment left by each grader. The student view of the any course staffs’ grades is the same as with non peer-grading assignments. +[![](/images/PeerImage5.PNG)] + +Coding of the peer grading system required changing Submitty’s SQL Databases and PHP Classes to introduce and differentiate between Peer Components/ Gradeables and non-Peer Components/Gradeables. It also required logical changes to Submitty’s PhP backend, which governs how assignments are graded and each user group has access to. Finally, various UI elements had to modified or added using Twig and Javascript. + +#### Students Giving Feedback to Peer Graders +Which the current Peer Grading System was functional, it did not allow the level of student interaction we aimed for. We were also worried that some students were less likely to receive quality feedback, based on who was assigned to grade them. To address these problems, we created a system which allows students to give the student-graders who graded them feedback on how helpful their comments were. Student graders will be able to see this feedback, letting them know how their grading was useful. Peer feedback is used as follows + +* The student clicks the “Switch to Feedback Mode Button” on the view grades page for the assignment. This changes the display of grades to show the marks selected by each peer grader adds several feedback options. + +* The student selects a feedback option. Only one feedback option may be selected. +[![](/images/PeerFeedback1.PNG)] + +* The peer grader opens the grading interface for that student. The peer feedback is visible in the Grading Rubric panel. +[![](/images/PeerFeedback2.PNG)] + +In the future, we plan to use this feedback and other measurements (like class performance) to develop a multi-dimensional metric, which can be used to sudo-randomly distribute peers in such a way that students are more likely to receive similar grades and comment quality. We are currently writing a paper about this metric and its possible use. diff --git a/_docs/developer/ms_phd_students/MS_2021_Hector_Rodriguez.md b/_docs/developer/ms_phd_students/MS_2021_Hector_Rodriguez.md new file mode 100644 index 00000000..6dcfa4e9 --- /dev/null +++ b/_docs/developer/ms_phd_students/MS_2021_Hector_Rodriguez.md @@ -0,0 +1,299 @@ +--- +title: Héctor D. Rodríguez Figueroa > MS > May 2021 +category: Developer > MS/PhD Students +redirect_from: + - /developer/MS_2021_Hector_Rodriguez +--- + + + + + +## What Is the Submitty Autograder? + +The Submitty Autograder is the component of Submitty responsible for compiling +and executing student code and comparing its output to an instructor’s +solutions. The autograder has three components to it: + + * Autograding workers. These are where student code is ultimately run and + their output graded. There may be multiple of these in a Submitty system, + and they may either be processes running on a Submitty *primary machine* + (the server which hosts the Submitty website), or they may be one or more + processes running on some *remote machine*. + * The autograding scheduler. Since we only have a finite number of autograding + workers, we can only grade so many student submissions at one time. The + scheduler determines which student assignments are graded first, as well as + which workers get to grade said assignments. + * Autograding shippers. There is one of these for every Submitty autograding + worker. They receive jobs from the scheduler and are in charge of sending + these jobs to their paired shipper. Once the job has been received by the + worker, the shipper periodically polls the job to see if it has finished + grading or not and, once it has finished, pulls the results back to the + primary machine and writes the grade data into the proper places. + +### The Life of a Submission + +A submission begins its life when a student clicks the “Submit” button on a +gradeable. From there, the submission’s files are uploaded onto the primary +machine, and a queue file is placed in the autograding queue folder. This +queue file identifies which submission should be graded as well as when it +was placed in the queue. + +The scheduler periodically polls the queue folder for new jobs. When the +scheduler finds jobs in the queue folder, it takes the oldest jobs and +moves them into the shipper directories of workers which are currently +idle (not grading any submissions). Once there, each queue file waits to +be sent to the worker by the shipper. + +Just like the scheduler, the shipper periodically scans its own directory +for jobs. When it detects a job placed in its directory, it opens the queue +file, packages the corresponding submission files into a zip file, and sends +the zip file to a place where the worker can see it. In the case that the +worker is a local worker, then it moves the zip file to the directory the +worker monitors. In the case that the worker is a remote worker, then the +zip file is sent over SCP to the remote worker. + +Once the worker picks up the queue file, it goes through the entire grading +process. This process can vary significantly depending on the gradeable’s +configuration. Once grading finishes, the worker creates a results zip file +containing the results of the autograding. On the shipper side, the shipper +queries the worker’s directory (either via local file management operations +or via SSH) periodically for the results zip file. Once the results zip file +is generated, the shipper pulls the results zip from the worker and extracts +it into the primary machine’s results folder, at which point the student is +able to see their submission’s results. Then, the cycle begins once again. + +## Motivation and Goals + +![Submitty Autograder Diagram](/images/hector_rodriguez_ms/submitty_autograder_before.png) + +The diagram above is a snapshot of the state of the Submitty Autograder when +I joined Submitty back in Fall 2019. Two things stand out about this design: + +1. There is no real scheduler. Instead, the shipper processes all fight each + other for jobs in the queue folder. This limits our ability to potentially + schedule autograding jobs in a more intelligent manner, as well as being + overall kind of a messy thing to deal with. +2. Autograding log entries are scattered everywhere throughout the system. + This is significant because it means that a system administrator would + have to inspect the primary machine’s logs to figure out on which machine + the issue occurred, so that they may then log on to the failing machine + (or machines, if the error occurs on multiple machines) and inspect the + logs there. It would be nicer to have copies of worker error logs available + on the primary machine. + +Not visible in the diagram is the maintainability of the system. The autograder +had grown organically over several years and, as a result, suffered from some +maintainability issues, particularly on the shipper end. Functions were very +long and their functionality was difficult to grok. Making changes to the code +was a very fear-wrought process, as the autograder code lacked unit tests, so +any small change could introduce a very subtle bug that wouldn’t be caught by +the site integration tests. Thus, my Master’s Project aimed at tackling this +issue. My contributions to Submitty can be summarized like so: + +1. [Scheduling](#scheduling) + 1. [Centralized Scheduling](#centralized-scheduling) + 2. [Short-Circuiting Non-Autograding Submissions](#short-circuiting-non-autograding-submissions) +2. [Logging](#logging) + 1. [Logging Centralization](#logging-centralization) + 2. [Student Logs (W.I.P.)](#student-logs-wip) +3. [Student Features](#student-features) + 1. [Autosaving in Notebook Gradeables](#autosaving-in-notebook-gradeables) + 2. [Grading Worker Display](#grading-worker-display) +4. [Refactors and Testing](#refactors-and-testing) + 1. [File Copy Refactor](#file-copy-refactor) + 2. [Vagrant Sample Courses Capabilities](#vagrant-sample-courses-capabilities) + 3. [Autograding Scheduler Unit Tests](#autograding-scheduler-unit-tests) + +## Scheduling + +### Centralized Scheduling + +Originally, there was no *true* autograding scheduler – any “scheduling” that +happened was a byproduct of the shippers’ original algorithm, summarized below: + +1. Lock the autograding queue directory. +2. Get a list of files in the queue directory that do not represent submissions + currently being graded. +3. Pick the oldest one, mark it as being graded, and send it to the worker. +4. Unlock the autograding queue directory. +5. Wait for the current submission to finish grading. +6. Retrieve the current submission’s results and save them. +7. Return to Step 1. + +Although this works, this has the potential issue of bottlenecking very easily +since at any given moment only one shipper can check for new jobs. This is +particularly noticeable on a system where the Submitty primary machine has +slow I/O. Furthermore, the decentralized nature of the scheduling behavior +limits what kinds of smart scheduling are possible. + +[PR #4745](https://github.com/Submitty/Submitty/pull/4745) modifies this +behavior so that scheduling decisions happen on the same thread that monitors +the shippers. Each shipper now queries its own private directory, so filesystem +locking is no longer necessary. Furthermore, scheduling happening on a +centralized process adjacent to the shippers means that it is easier to modify +the scheduling behavior. The image below showcases the autograder’s structure +after the changes made by this PR. Note the new “scheduler” node and how it +pushes jobs to each shipper node. + +![Submitty Autograder with the new scheduler](/images/hector_rodriguez_ms/submitty_autograder_with_scheduler.png) + +### Short-Circuiting Non-Autograding Submissions + +[PR #5527](https://github.com/Submitty/Submitty/pull/5527) allows for +submissions we deem as “trivially gradeable” to skip most of the autograding +process. We currently define a trivially gradeable submission as one that +only has a lateness check associated with it. When a shipper picks up a job +that is trivially gradeable, it performs the lateness check itself, docks +points if necessary, and records the submission’s results. Because this skips +the worker portion of the autograding process, such submissions are now graded +much more quickly than before. + +## Logging + +### Logging Centralization + +The Submitty autograder writes two different types of logs: regular logs, and +stack trace logs. Regular logs simply provide transparency into how the +autograder is currently running, whereas stack trace logs report major errors +that occur. The Submitty primary machine and each of the worker machines keep +their own independent copies of both logs. This means that inspecting the logs +when autograding failures occur can become a bit of a hassle, as it may be +necessary to log into one or more worker machines to find out what went wrong. + +[PR #6062](https://github.com/Submitty/Submitty/pull/6062) revamps the +autograding logger interface so that stack trace logs are replicated in a +central location (the Submitty primary machine) when possible. The worker +keeps track of all calls to the “log stack trace” function, and stores this +record in its results file. When the corresponding shipper receives the results +file and discovers that the “log stack trace” function was called on the +worker’s end, it reproduces those entries in the primary machine’s stack trace +log. The image below showcases the state of the autograder after pushing +this change. Note how the primary machine now also includes logs from the +worker machine, respecting the order with respect to the worker machine. + +![Submitty Autograder with centralized logging](/images/hector_rodriguez_ms/submitty_autograder_scheduler_logs.png) + +### Student Logs (W.I.P.) + +Currently, if a submission suffers from some kind of autograding-related +error, the student receives a message stating “Something went wrong with this +submission.” This is admittedly not a very helpful error message, and figuring +out the source of the error usually involves an administrator looking through +the autograding logs to figure this information out. The goal of the +tentatively-named “Student Logs” feature is to provide extra feedback to the +user on autograding failure so that narrowing down the source of the issue +is a more streamlined process. For instance, if autograding fails due to a +Docker misconfiguration in the gradeable, this information can be propagated +to the instructor much more quickly. + +## Student Features + +### Autosaving in Notebook Gradeables + +[PR #5323](https://github.com/Submitty/Submitty/pull/5323) introduces +autosaving to notebook gradeables. This is part of an ongoing initiative to +help reduce the load on the autograder when notebook gradeables are used for +distributing exams. Students may submit multiple times to these gradeables as +a method of saving their progress. Notebook autosaving is local-only, but it +helps safeguard a student’s exam progress from potential catastrophe (e.g. a +browser crash) without having to use up the worker’s available compute for +results that are ultimately going to be discarded anyway. + +### Grading Worker Display + +[PR #6175](https://github.com/Submitty/Submitty/pull/6175) introduces a new +“graded by worker” field to the autograding results page. Although minor, this +tweak can significantly help gradeable debugging time when dealing with +heterogeneous sets of workers. For example, consider a setup with two workers +`A` and `B` set up to grade graphics assignments. `A` and `B` have different +graphics cards, and as a result might have slight inconsistencies in how they +render graphics. Because of these inconsistencies, one student might lose +points when grading on worker `B`, but not when grading on worker `A`. +Displaying which worker machine graded a submission helps with debugging these +instances, as it is no longer necessary to dig deep into the autograder logs +to figure out which worker graded a certain submission – this information can +be provided directly by the student. + +## Refactors and Testing + +### File Copy Refactor + +[PR #5867](https://github.com/Submitty/Submitty/pull/5867) introduces a suite +of generic “copy/delete” functions to the autograding shipper that decide based +on the destination hostname whether the file access should be done via the +operating system’s regular local file management functions (for managing files +on workers running on the primary machine) or via SSH (for managing files on +remote workers). This helps make the surrounding code easier to understand, +as the functions where these file management operations occur are shorter as +a result and easier to understand. The table below shows the line counts of +the refactored functions before and after the refactor. + +| Function | Line Count (Before) | Line Count (After) | +| -------------------- | ------------------- | ------------------ | +| `update_worker_json` | 105 | 54 | +| `prepare_job` | 119 | 92 | +| `unpack_job` | 224 | 186 | + +### Vagrant Sample Courses Capabilities + +Each gradeable that can be autograded is assigned a *capability* by the +instructor. This tells the autograding scheduler which workers are allowed +to grade this and allows for a Submitty setup to have workers dedicated to +specific tasks. For example, there could be one worker machine dedicated to +running Python assignments, one worker machine dedicated to running C++ +assignments, etc. + +[PR #6264](https://github.com/Submitty/Submitty/pull/6264) modifies the setup +scripts for the development VM environment so that the sample courses have +multiple capabilities associated with them. This lays the groundwork for more +sophisticated testing of the autograding infrastructure. + +### Autograding Scheduler Unit Tests + +[PR #6191](https://github.com/Submitty/Submitty/pull/6191) introduces unit +tests for the autograding scheduler, while also refactoring the scheduler’s +behavior into its own separate class following a specific interface. Unit tests +for the scheduler help improve our testing coverage of the Submitty autograding +infrastructure, whereas refactoring the scheduler into its own separate class +lays the groundwork for more configurable autograding scheduler behavior. For +example, one administrator may want to preserve First-Come-First-Serve +scheduling, whereas another administrator in a different institute might prefer +some other scheduling algorithm. + +## Future Work + +### Scheduling and the Thursday Problem + +The current scheduling algorithm used in Submitty is a very simple +first-come-first-serve algorithm. While it is “fair” in a sense, issues arise +when it comes to mixing and matching different classes. This manifests in +something I like to call “The Thursday Problem:” at RPI, one of the +introductory Computer Science courses, Data Structures, schedules homeworks +weekly to be turned in by the end of day on Thursday. As it is an introductory +course, there are hundreds of students enrolled in it at the same time. This +means that every Thursday, Submitty gets flooded with hundreds of Data +Structures submissions as the midnight deadline approaches. + +At the beginning of the semester, this can pose a minor annoyance to students +taking higher level courses, such as Operating Systems. In these higher-level +courses, homework code tends to be more complex and as a result takes longer +to grade, although there tends to be far fewer students in these courses and +homeworks are far more spread out. +This means that students of these courses who find themselves in the unfortunate +position of submitting on a Thursday night will get caught in the flood of Data +Structures submissions and may find themselves waiting several minutes until +their submission begins grading. This becomes more and more of an issue as the +semester goes on – Data Structures assignments become more complex and therefore +require more time to grade, which means our hypothetical Operating Systems +student could be waiting for over half an hour for feedback if they’re unlucky. + +Because of this, it would be interesting to experiment with various different +scheduling algorithms in order to make a system that’s perhaps more “fair” in a +different sense of the word. Furthermore, a more sophisticated algorithm could +help overcome some trickier constraints. For example, a worker might have the +computational capacity to grade multiple small assignments or one big +assignment. How “heavy” an assignment is is not something that the scheduler +currently takes into account. diff --git a/_docs/developer/ms_phd_students/index.md b/_docs/developer/ms_phd_students/index.md new file mode 100644 index 00000000..8fef69ea --- /dev/null +++ b/_docs/developer/ms_phd_students/index.md @@ -0,0 +1,19 @@ +--- +title: Overview +category: Developer > MS/PhD Students +redirect_from: + - /developer/ms_phd_students + - /developer/poster_session +--- + +### PhD Thesis + +* Evan Maicus - PhD - *Expected May 2021* + +### Masters Thesis / Projects + +* [Hector Rodriguez - MS - *Expected May 2021*](MS_2021_Hector_Rodriguez) + +* [John (Jack) Hulton - MS - December 2020](MS_2020_John_Hulton) + +* Evan Maicus - MS - December 2018 \ No newline at end of file diff --git a/_docs/developer/php_unit_tests.md b/_docs/developer/php_unit_tests.md deleted file mode 100644 index 85edb13e..00000000 --- a/_docs/developer/php_unit_tests.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: PHP Unit Tests -category: Developer -order: 8 ---- - -These are general details and instructions for testing the PHP code -(both Unit and End-to-End). OS specific instructions are below. - -The primary method of testing for the PHP code is _Unit Testing_ (we -also do End-to-End testing, but that is covered in a different -section). These tests require that you have -[PHPUnit](https://phpunit.de/) on your system. - -You can either get the .phar files for it or much more easily use -[Composer](https://getcomposer.org/) to handle this for you. From the -root of the repository, simply run: - -``` -composer install -``` - -This will download PHPUnit and PHPUnit-Selenium to the local machine -and make it available via the vendor directory. - -Note: If you're using PHP 5.5, you'll first need to run the command - -``` -cp composer_55.json composer.json -``` - -From there, to run the unit test suite, you can run from the root: - -``` -vendor/bin/phpunit --configuration tests/phpunit.xml -``` - -## Mac Installation - -If using a Mac computer, the following commands can be run to set -everything up for you for testing (assuming you've installed -[Homebrew](https://brew.sh/): - -``` -brew tap homebrew/dupes -brew tap homebrew/versions -brew tap homebrew/homebrew-php -brew install php56 -brew install composer -composer install -vendor/bin/phpunit --configuration tests/phpunit.xml -``` \ No newline at end of file diff --git a/_docs/developer/project_ideas.md b/_docs/developer/project_ideas.md deleted file mode 100644 index f591d4d4..00000000 --- a/_docs/developer/project_ideas.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Project Ideas -category: Developer ---- - - -The projects listed below are roughly ordered by prior experience -required. Work has already begun on many of these projects, but we -are looking for new team members to join these projects. Submit -questions or comments on specific issues through our -[Submitty GitHub Issue Tracker](https://github.com/Submitty/Submitty/issues) -or [Contact Us](http://submitty.org/index) to join the -development team. - - -1. **Peer Grading** - - Currently we facilitate detailed rubric manual grading of student - assignments by the instructor or TA. We have extended this design - to include peer assessment, which can aid timeliness, quantity, and - quality of feedback for students in large courses, especially those - with limited instructional resources. Furthermore, research has - shown that peer grading and feedback also provides important - benefits to the peer graders! - - When peer grading is enabled students will be assigned to review - and critique a small number of their classmates' work. The - core implementation of peer grading is in progress, but incomplete. - - [Open Issues related to Peer Grading](https://github.com/Submitty/Submitty/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+peer) - - Advanced features related to peer grading: - - * Evaluating the quality of peer grading ("grading the grader") by - comparing peer grades. - - * Security (ensuring students only see the submission material of - peers they have been assigned to grade). - - * Privacy/Anonymity (providing an option to redact student names - from material seen by peers). - - Experience Required: Some programming experience, willingness to - learn web and database development. - - -2. **Discussion Forum** - - A new feature for Spring 2018 is a Discussion Forum where - instructors can post announcements, students can ask questions, - instructors/TAs/other students can answer questions, and students can - share ideas and images. - - [Open Issues related to the Discussion Forum](https://github.com/Submitty/Submitty/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+forum) - - Advanced features related to the Discussion Forum: - - * Team chat - - * Notifications - - * Performance with larger datasets and automated refresh for new posts. - - Experience Required: Some programming experience, willingness to - learn web and database development. - - -3. **Instructor interface for Plagiarism Detection** - - The initial implementation of the core plagiarism detection - algorithm is complete. And we have an initial visualization of - similarities between the top matching pairs of assignment - submissions. Outstanding work includes testing and debugging, - detection of common code (e.g., instructor-provided code), - extension to languages other than Python, C/C++, and Java, more - intuitive visualization (to allow the instructor to make final - decision on plagiarism vs. coincidental matching. - - [Open Issues related to Plagiarism Detection](https://github.com/Submitty/Submitty/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+plagiarism) - - Experience Required: Some programming experience, willingness to - learn web and database development. Experience with a wide variety - of programming languages is beneficial. - - -4. **Web GUI for creating automated grading configurations** - - Currently instructors must write a configuration as a config.json - (and any necessary additional files) and upload or store these - files on the local file system. We would like to provide an - alternate web GUI interface for creating basic on moderately - complex autograding configurations. The goal would be to - streamline the assignment configuration process for non-technical - instructors, relevant for use in - non-computer-science/non-programming courses. - - [Assignment Configuration Instructions](http://submitty.org/instructor/assignment_configuration) - - Experience Required: Some programming experience, willingness to - learn web and database development. Having served as a teaching - assistant or instructor with experience in programming assignment - design will be beneficial. - - -5. **Static Analysis** - - -6. **Website Security and Penetration Testing** - - Submitty is responsible for securing confidential information. It - is important that we regularly assess the security of this data. - Once a potential vulnerability is found, the system must be - promptly patched and documented to prevent future problems. - - Experience Required: Computer security coursework and/or practical - experience searching for system vulnerabilities. - - -7. **Continuous Integration Testing** - - Each commit and pull request to github launches continuous - integration testing of a portion of the Submitty code base. We - would like to expand the coverage of the code - - Experience Required: Advanced programming experience, experience - with the relevant programming languages, tuning system performance, - - - - -See also: - -* [Submitty GitHub Issue Tracker](https://github.com/Submitty/Submitty/issues) - -* [Developer](index) index page - -* [How to Contribute](how_to_contribute) page - - diff --git a/_docs/developer/rensselaer_center_for_open_source/2021_Chris_Reed.md b/_docs/developer/rensselaer_center_for_open_source/2021_Chris_Reed.md new file mode 100644 index 00000000..f7a61f3a --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2021_Chris_Reed.md @@ -0,0 +1,54 @@ +--- +title: Chris Reed +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2021 +redirect_from: + - /developer/rpi_summer_rcos/2021_Chris_Reed.md +--- + +Throughout the summer, I worked on various new features, bug fixes, and refactors for Submitty. All of my work can be seen +[here](https://github.com/Submitty/Submitty/commits?author=cjreed121) and is documented below. + +### SQL Toolbox + +This was the first area I started to work on with Submitty. I added a few features to this area of Submitty: + +- Added row numbers to the query result +- Added functionality to download a CSV file of the query result +- Added schema information above the query box for instructors to see all tables in fields in the database. + +### Course Materials + +I worked on a refactor of the course materials page of Submitty. Before, all data for course materials was stored in a JSON file on the system. +Now, all information about course materials are stored in the Postgres database. This also uses Doctrine for entities to represent each course +material. There was no clear MVC structure before which there now is. This required writing migrations to read the old JSON data while inserting +into the database, adding a model to the current site, and then finally a massive rewrite of the view and controller to support this new model. + +After the refactor I worked on a few new features to course materials. My first feature was allowing for instructors to edit links after they +have been uploaded. Before this feature any link would had to have been deleted, reuploaded, and reconfigured. Another feature I worked on was +the addition of a new tag next to all course materials the user has not viewed. This makes it easy for students to find any new materials their +instructor has put up. I additionally rewrote some of the routes to support accessing course materials by their database ID so shorter and less +complex URLs could be used on the site. + +### Gradeables + +While working on Submitty I got to add a few features to gradeables. One feature I added was the addition of a timer to the gradeable page. +This timer could be used for simply telling when your homework is due or telling you exactly how much time you have left on a test. When a test +timer is visible, a progress bar of how far along you are in the test would also show. This is a feature I would have liked to see on Submitty +in the past. This required having an accurate Javascript timer, a method to sync back with the server periodically, and a way for gradeables to +store their allowed minutes in the database when being built. + +Another feature I implemented was the ability for instructors to choose an order for which gradeables should be completed. This forces students +to complete a certain assignment before being allowed to open and submit the next assignment. This could be used in work at your own pace classes +or in crash courses. + +### Secondary Email + +I added the ability for all Submitty users to add a secondary email address to their profile. This would allow for them to receive email to that +address in addition to their primary address. It would also allow for instructors to get ahold of students in the event the primary email +addresses were not functional. + +### Smaller tasks + +- Identified and fixed a few security issues +- Added ability for teams to choose names +- Storing Unix groups in database for easy access \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2021_Eddie_Krystowski.md b/_docs/developer/rensselaer_center_for_open_source/2021_Eddie_Krystowski.md new file mode 100644 index 00000000..b5ed4e6d --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2021_Eddie_Krystowski.md @@ -0,0 +1,59 @@ +--- +title: Eddie Krystowski +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2021 +redirect_from: + - /developer/rpi_summer_rcos/2021_Eddie_Krystowski.md +--- + +In the summer of 2021, I worked mainly on improving and standardizing various aspects of the user interface, especially in dark mode. I also worked extensively with markdown support, the PDF editor tool, and allowing developers to create a mock worker machine using Vagrant alongside the main Submitty virtual machine. + +### Dark Mode +Dark Mode is a feature that allows the user to change the overall look of Submitty to one with a darker palette. Some of the work I did regarding dark mode consisted of: +- Improving the consistency of dark mode throughout the site +- Refactoring stylesheets to properly use dark-mode colors +- Fixing low contrast areas, especially in less frequently visited pages, by using WAVE (Web Accessibility Evaluation Tool) to ensure a 7:1 minimum contrast ratio across most pages. + - I fixed the contrast of code boxes in dark mode which were very difficult for students to use due to the syntax highlighting not considering the site theme. + + +### Markdown +Markdown is a simple markup language that allows users to easily format text with italics, bullet points, links, etc. all while writing with plaintext. It is used in many spots on the site, such as the discussion forum, Submini polls, gradeable configurations, and pretty much anywhere else that formatted text would be useful. + +- Implemented a new Markdown engine, (league/commonmark) + - This new engine allows for greater control of markdown behavior, as well as customizable parsing and rendering of specific components. + - This engine allowed me to greatly improve the behavior of markdown code boxes to be able to show line numbers based on code box size and have proper syntax highlighting based on language and site theme. +- Standardized Markdown across all of Submitty + - All markdown related styling was moved to its own stylesheet and only contains what is necessary, no page specific styling is included. + - Twig templates have been added so that any page that wants to use Markdown display/input simply includes the template and it just works. +- Improved markdown input interface + - Created input interface as a standalone component that can be added to any page. + - Input interface is fully accessible through keyboard alone. + - Write Mode + - Users can enter plaintext + - There are predefined shortcut buttons that will insert templates for formatting common types such as bold, italics, links, etc. These were already implemented, but had some bugs and were not used consistently. + - Preview Mode + - Users can see what their markdown will look like once rendered. + +### PDF Editor +The PDF Editor tool is a tool for TAs and instructors that allows them to annotate student-submitted PDFs. A lot of my work on this page consisted of trying to create a quicker and easier user experience for whoever was using the page. + +- Greatly improved zooming speed +- Improved mobile tablet experience +- Remembered settings per gradeable + - Ex: If a user zooms in 150%, and then goes to the next submission, they will still be zoomed in that same amount. +- Fixed issues that would cause PDF annotations to become corrupted. + - Also implemented a system to detect corrupted annotations and attempt to fix them. + - Corrupted annotations can only be permanently fixed by those who made them, but they will be temporarily fixed so that others can make their own annotations. +- Added toolbar buttons + - Rotate Left + - Clear + - Show/Hide Other User's Annotations + - Custom pen colors from a color picker + +### Vagrant Worker +In the real Submitty environment, there are worker machines which share the load of autograding from the main machine, and could potentially have different capabilities as well. I implemented a configuration option that allows developers to create and run their own worker virtual machine alongside the main Submitty virtual machine to allow for easier debugging and testing of related features. + +- Changed setup scripts to allow for simultaneous provisioning of both the main Submitty VM as well as the worker VM + - Automates steps 1-7 of [the worker installation instructions](/sysadmin/worker_installation). +- Added command to start worker VM alongside Submitty VM + +See the [Virtual Box Worker](http://localhost:4000/developer/worker_vm) instructions for more information. diff --git a/_docs/developer/rensselaer_center_for_open_source/2021_Henrik_Lam.md b/_docs/developer/rensselaer_center_for_open_source/2021_Henrik_Lam.md new file mode 100644 index 00000000..05388046 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2021_Henrik_Lam.md @@ -0,0 +1,105 @@ +--- +title: Henrik Lam +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2021 +redirect_from: + - /developer/rpi_summer_rcos/2021_Henrik_Lam.md +--- + +In the summer of 2021, I mostly worked on creating new pages for instructors, sysadmins, and faculties. +Most of these pages are meant to bring out information that is only available to those who have SSH access +into the Submitty machine or those who have access to our database. Through these page, the non-student +users of the system will be better informed on the status of the System and be more confident when +using our system. In addition, they will also be able to better understand the status of the system as +compared to when they had to go through the ssh or the sysadmin to get the information or confirmation +they need. + +## Email Status + +Throughout the Submitty system, there are a couple places where emails are sent to notify the users. +This includes the forum messages and regrade requests which are widely used in each course. However, +to see the status of the email sending requests they must either contact the system administrator, +or access the Submitty database. This page served to bridge the gap between the faculties and the +email database on our system. To implement this page, I had to + +- Change the existing database to allow emails to be associated with the course it was sent from +- Read the appropriate emails based on the user accessing the page +- Parse and display the results from the database in a comprehensive manner + +I also eventually brought the page to the system administrators, which required me to + +- Switch backend's traditional sql query string to use DoctrineORM instead to simplify future work +on the email database +- Create a pagination on the email results and a dynamic webpage based on the page specified through +AJAX requests +- Design a strategy for the page to load and display a set amount of emails to avoid overloading +the server and the user +- Create a python script to insert sample emails when the development environment is being set up +to ensure the system will not be overloaded + +## Sysadmin Email All Page + +This page was designed to allow the system administrators to contact the Submitty users. Some cases +in which this might be used is when there is in times of an emergency in which the users need to be +contacted through the secondary emails the users specified in their profile, and when there is a +big feature change which the instructors need to be aware of. For this page, I had to + +- Query the database to show how many people will be emailed +- Query the database to get the level of access that the emails should go to, which is defined by the +sender. The levels are broken down into: + - Faculties + - Instructors + - Full Access Graders and up + - Limited Access Graders and up + - Students and up +- Insert the emails as appropriate into the database + +## Student Activity Dashboard + +This page was designed to allow the instructors to monitor the students' activities on the system +so that the instructors can be sure the students are staying up to date on the course work, and also +allows the instructors to reach out to the student before it is too late. This page was originally designed +by Roland Rao, and I took over his work for the Summer. In this feature, I contributed by +- Polishing the UI of the dashboard +- Optimizing the sorting of the results and modularizing the comparison between different columns +- Altering the database query to show accurate results +- Finishing the download feature which allows the user to download a csv representation of the dashboard + +## Docker UI + +This page was an existing page on the system which I revamped during this Summer. This page allows the +user to see the details and credentials of the docker containers installed on the system. The work which +I have done on this page include +- Logging of the updates on the machines and its docker images + - Parsing the logs to spot any failures in the last update on either machines or images + - Logging the last time an update was done +- Getting the interesting docker related information from the system + - To do so, I originally used the pre-existing CGI script which uses the docker python library to + access all relevant information on the primary + - I eventually moved this to a python script to be called on both primary and worker machines to gain + information on all the docker images as well as the machines themselves + - Access the worker machine through SSH calls with the pre-exisitng ssh_proxy_jump class to call the + docker update and log the output from the worker machine +- Wrote a new Daemon Job to update the docker information +- Added a button to update the system, allowing the instructors to update the system as appropriate +- Added a functionality on the page to allow the instructors to add a docker image to an existing capability + - Checks the specified docker name through Regex to see if the format is appropriate + - Pings the Docker V1 API to see if the docker exists + - Edits the autoworkers_containers.json file + - Queue the system to update both the primary and worker machines through the Daemon Job + +## Autograding Status +This page serves as the gap between the instructors and the autograding status of the system, which is another +piece of information on the system only available to those with SSH access to the machine. On this feature, I +had to +- Write a new python script which traverses the directories in the system to monitor the queue files +- Monitor what is currently being graded and what is in the queue + - Categorizes the jobs based on whether it is a regrade job or a non-regrade job + - Display the jobs currently being graded + - Shows the gradeable id and the course from which the job originated from +- Determine what courses the user has instructor access to + - Display the job's owner's user id if the current user has instructor access to the job's originating course +- Periodically update the page to give the user fresh and relevant information + - Dynamically add the status of the autograding system as a row in a table to allow better monitoring of the + system's progress + - Added a button to pause and unpause the updating of the page in case they want a snapshot of the state of + the machine \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2021_Miles_Ednie.md b/_docs/developer/rensselaer_center_for_open_source/2021_Miles_Ednie.md new file mode 100644 index 00000000..924a4121 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2021_Miles_Ednie.md @@ -0,0 +1,77 @@ +--- +title: Miles Ednie +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2021 +redirect_from: + - /developer/rpi_summer_rcos/2021_Miles_Ednie.md +--- + +This summer, I spent the majority of my time working on the backend of +the site with PHP. I became proficient in working with our +model-view-controller framework to add features and fix bugs. I spent +the rest of my time working with jQuery/javascript, HTML, Twig and CSS +on the front end. I was able to combine my skills across both ends of +the site to solve tough problems and make some great additions to +Submitty. + +As a student I never saw the Instructor/TA side of Submitty but that +is where I spent most of my time while working as a developer. I +worked on the TA grading interface, rubric configurations, peer +grading and much more. I added easy to use buttons to allow +instructors to regrade their student's submissions which could +previously only be done from the command line. This involved adding +functions to create files that contained all of the necessary +information for the workers and shippers to be able to do their job +and regrade the submissions. + +As a freshman, my classes didn’t use peer grading, but I heard about +it and was interested in working on it as a developer because I know +how helpful it could be to students. I spent a lot of time working on +the peer grading rubric, squashing as many bugs as I could so that the +feature could be used more across RPI and beyond. A lot needed to be +done from a privacy perspective so that peer graders couldn’t access +too much information about the students that they were grading. This +took a lot of work on the backend with all sorts of permissions +checking and new functions to properly display the correct information +to the right people. I hope to use peer grading in my future classes +to really test my work and benefit from the system. + +The Submitty rubric has a “custom mark” option where a grader can give +however many points they want and leave whatever comment they want. A +lot of people love this feature but there were complaints from people +in large classes that they’d rather not have custom marks in order to +keep consistency when grading classes with hundreds of students. In +order to solve this, I added a setting that allows instructors to +choose if they want custom marks to be allowed on the rubric for an +assignment. I also added and improved grading statistics to help out +TA’s and instructors. + +Unrelated to TA grading but still on the backend, I added a feature +that allows Instructors to specify regex patterns that a student’s +contact information must match in order for them to enter the office +hours queue. This was helpful because with online learning it seemed +to be a frequent problem that a student would enter the wrong type of +link or email address when entering the queue, and then it made it +hard for the mentor or TA to help them. In addition, I also +implemented the ZipStream library in multiple places across the site +to allow users to download folders in an efficient way. + +On the frontend I used jQuery to do a complete refactor of the code +that autosaves test answers for students. The way it was previously +implemented had a bug that could lead to data loss, so a total +refactor was necessary. I had to figure out how to use jQuery +selectors to save answers from all different types of questions +(multiple choice, multiple select, short answer and code boxes) to +local storage and then restore them properly. I hope my work saves a +few people some major headaches in the future. I also used jQuery to +implement a popup that appears during tests and quizzes. The popup +has a button that allows students to submit their current progress so +that time doesn’t run out on them before they can submit their work. +I had to tie the popup into a timer that used the server to keep an +accurate time because we wanted the popup to appear every x number of +minutes depending on the total time allowed. + +Working for Submitty was my first job as a developer, and I learned so +much. From the technical things, to working on a development team and +to working on open source software in general. I look forward to +making more contributions to this great project in the future as I +progress as a developer and a computer scientist. diff --git a/_docs/developer/rensselaer_center_for_open_source/2021_Shelly_Belsky.md b/_docs/developer/rensselaer_center_for_open_source/2021_Shelly_Belsky.md new file mode 100644 index 00000000..b9f888b7 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2021_Shelly_Belsky.md @@ -0,0 +1,48 @@ +--- +title: Shelly Belsky +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2021 +redirect_from: + - /developer/rpi_summer_rcos/2021_Shelly_Belsky.md +--- + + +### Lichen Plagiarism Detection +I worked together with [William Allen](https://github.com/williamjallen) on Lichen, Submitty's Plagiarism Detection Tool -- a partially-functional feature last touched 3 years ago. We worked on it all summer to fix the base infrastructure, implement new features that were on the wish list for Lichen, and pulled everything together into a fully working state. + +- Overhauled the core hash comparison algorithm that finds matches +- Implemented new features: + - Recognizing [common code](/instructor/course_management/plagiarism#common-code-threshold) across student submissions + - Uploading [instructor provided files](/instructor/course_management/plagiarism#instructor-provided-code) and not marking matching code plagiarized + - Ability to specify submitted [files to be compared](/instructor/course_management/plagiarism#files-to-be-compared) + - Ability to specify [ignored users](/instructor/course_management/plagiarism#users-to-be-ignored) to not be included in the matching algorithm + - Ability to process [active or all versions](/instructor/course_management/plagiarism#version) of users who made submissions + - Comparing for matches against [other gradeables](/instructor/course_management/plagiarism#other-gradeables) from prior terms + - Added ability to create multiple plagiarism detection configuration per gradeable +- UI appearance and functionality improvements to all the plagiarism pages, especially the page displaying the plagiarism results +- Features for Lichen developers: + - Made an additional development course for the VM setup containing gradeables with sample submissions to be used as different test cases of the plagiarism tool, each with their own documentation + - Created individual ranking files containing the top matches for every user in the hash comparison algorithm + - Overhauled the Lichen directory structure + - Added unit and integration testing to the Lichen repository + - Other optimizations and modifications to the programs involved in Lichen runs + - Added thorough documentations of all the new features and a guide for new Lichen developers + +### Submini Polls +Submini Polls is a lecture polling system for instructors that can be enabled to gather quick information or quiz students on lecture material. This summer I added new types of polls to supplement the basic existing functionality of the feature, increased coverage of testing, and fixed bugs. This newly improved feature will be used to replace iClickers in future classes. + +- Added different types of polls: single response, multiple response, with different grading settings +- Finished implementing incomplete picture attachment feature +- UI appearance and functionality improvements to the polls summary page and the new poll page +- General bugfixes with poll creation and addition/deletion/order change of responses +- Added unit testing for the poll model +- Added a Cypress e2e test for polls + +### Submitty Developers and Miscellaneous Contributions +Besides working on specific features, I made a number of other miscellaneous contributions across Submitty. I also contributed significantly to the developer resources by creating data for development courses, and creating an entirely new development course for testing Lichen. Small tweaks that perfect features over time are what ultimately pull the project together. + +- Added sample data to the sample course to be added automatically during setup: + - The office hours queue page + - Submini Polls + - A gradeable with VCS submissions +- Made small UI appearance changes on various pages on the site +- Reported several bugs encountered and submitted feature/testing requests diff --git a/_docs/developer/rensselaer_center_for_open_source/2021_William_Allen.md b/_docs/developer/rensselaer_center_for_open_source/2021_William_Allen.md new file mode 100644 index 00000000..ff0531fc --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2021_William_Allen.md @@ -0,0 +1,45 @@ +--- +title: William Allen +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2021 +redirect_from: + - /developer/rpi_summer_rcos/2021_William_Allen.md +--- + +### Summary +I spent the majority of the summer working with Shelly Belsky to give Lichen a +complete overhaul, turning it into a mostly-functioning plagiarism detection tool +with the ability to detect code plagiarism in C++, Python, Java, and MIPS. At +the start of the summer, there was little which worked and even the most basic +functionality was broken. By the end of the first week in June, I had managed +to get Lichen working in a primitive state, just as long as you didn't try to do +basic things like edit a configuration after it was created, provide any invalid +input values, or attempt to use anything other than the plaintext or C++ tokenizers. +Shelly joined the effort in the middle of June when we decided to completely +rewrite the main hash comparison algorithm for Lichen to occupy ourselves over +the course of a weekend. We then went on to fix the remaining issues with lichen +and the plagiarism interface, before implementing almost all of the features on +the original outline and resolving most of the open issues for Lichen. +By the end of the summer, nearly every line of code in Lichen and in the +Plagiarism Interface had been overhauled. + +As of now, all of the initial implementation of Lichen is complete and future work +should largely iterate upon the existing code. Lichen is currently capable of +detecting similar code in C++, Python, Java, and MIPS, as well as identifying +regions of code common to many users and code which is similar to instructor-provided +code files. It is also possible to compare code against submissions from prior terms. + +I also spent a quantity of time fixing bugs across the codebase and improving +Cypress end-to-end tests. + +### Future Work +As of now, there are a few key parts of Lichen which need to be refined. All +of the current code is believed to work as intended, but a handful of wishlist +features have yet to be implemented and some portions of the system still require +refinement. In particular, future work is needed on the following general areas: + +1. Improvements to the ranking system to make it comparable to MOSS in effectiveness +2. Automatic re-run abilities +3. Plagiarism interface color scheme +4. Migration of the plagiarism interface to CodeMirror 6 +5. Overhaul of the tokenization system to use tree-sitter parsers +6. Containerization of Lichen and ability to deploy Lichen to worker machines diff --git a/_docs/developer/rensselaer_center_for_open_source/2022_Evan_Bowen_Shi.md b/_docs/developer/rensselaer_center_for_open_source/2022_Evan_Bowen_Shi.md new file mode 100644 index 00000000..3adddb1d --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2022_Evan_Bowen_Shi.md @@ -0,0 +1,31 @@ +--- +title: Evan Bowen Shi +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2022 +--- + +In the summer of 2022, I spent the first month learning the design and structure of submitty as well as the basics of languages such as PHP and JavaScript to get myself started. Then, for the rest of the summer, as I became more familiar with Submitty and I worked mainly on improving various aspects of PDF functionalities in the grading interface, especially in PDF annotation. I also spent a significant amount of time working on the expected string feature, which allows the usage of "expected_string" on assignment configurations. + +### PDF annotation +PDF annotation is a feature that allows graders to make custom marks over submitted PDF files during grading. Some of the work I did regarding PDF annotation consisted of: +- Updated the pdf-annotate.js package and fixed the issues related to creating custom marks. +- Improved the view/download functionality in the grading interface for annotated PFD files for security purposes. +- Created sample gradables that use PDF annotation functionalities inside the development environment for testing purposes. +- Removed numerous server-side errors. +- Resolved minor user-interface misalignment in the grading results interface. + +### Expected String +When creating a new gradeable, instructor users need to specify the full path to the auto-grading configuration config.json file, where they can only set answers by giving a file and using the "expected_file" option. Therefore, I provided an alternative usage of "expected_string" so that instructor users can enter the solutions in a string format. In addition to the feature, I added samples and automatic testing cases. The implementation is based on Eddie Krystowski's previous work. + +### Smaller Tasks +Here are some smaller front-end oriented tasks I worked on this summer: +- Fixed the elements overlapping issue in mermaid sequence diagrams for network gradeables. +- Enhanced the simple-grading interface by removing ambiguities. +- Polished the bulk-submission interface. + +### Future Work +In my work to add the expected string functionality, I noticed that the code responsible for creating the diff-view for the expected and actual solution locates mainly inside a custom class called DiffViewer. Since the code was written long ago and the implementation is rather lengthy, I believe it is best to refactor the functionality using CodeMirror entirely. Even though I am unlikely to finish the work this summer, I plan to continue working on the diff-view refactoring as I transition into the coming fall semester. In particular, future works are needed in the following general areas: +- Using CodeMirror's merge addon for displaying the diffs. +- Preserving the "Visualize whitespace characters" functionality through CodeMirror. +- Designing the desired diff-view interface. + - Side by side versus stacked view. + - Handling of extra wide output. diff --git a/_docs/developer/rensselaer_center_for_open_source/2022_Jerry_Jiarui_Lu.md b/_docs/developer/rensselaer_center_for_open_source/2022_Jerry_Jiarui_Lu.md new file mode 100644 index 00000000..3e8e69da --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2022_Jerry_Jiarui_Lu.md @@ -0,0 +1,63 @@ +--- +title: Jerry Jiarui Lu +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2022 +--- + +As a first-time developer, the initial few weeks were spent on +familiarizing myself with the codebase and setting up virtual machines. +Once I felt more comfortable and confident, I worked on smaller system- +related features such as Docker UI and worker status reports. + +As the summer progressed, I was able to contribute to the auto-grading +system as well as new continuous integration checks. In addition, I +also spent a significant amount of time implementing and porting the +development and test environments to HTTP/2 with TLS. + + +### Auto-grading Features/Bug fixes + +- Logging errors from the auto-grading code runner; + +- A string parser for submission size in gradeable configs; + +- Fixed a possible racing condition in bulk regrading with workers; + +- Gradeable-level build log. + + +### Worker Features + +- Worker auto-exit when the disk space is critical; + +- Refined Docker UI with more system information (services, OS, etc.); + +- Worker update excluding list. + + +### System Features + +- Scripts for dispatching daemon jobs; + +- HTTP/2 for development, production and test environments; + +- Scripts for generating, trust certificates system-wide. + + +### Misc + +- Fixed missing images in Submini Polls; + +- An auto-grading example with point deduction; + +- CI checks for database dumps; + +- Removed hard-coded arguments in scripts for creating sample courses; + +- Fixed a permission error when displaying course materials. + + +### Future Work + +- Fine-grained Docker permission control; + +- HTTP early hints. diff --git a/_docs/developer/rensselaer_center_for_open_source/2022_Matthew_Bonnecaze.md b/_docs/developer/rensselaer_center_for_open_source/2022_Matthew_Bonnecaze.md new file mode 100644 index 00000000..1a408b57 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2022_Matthew_Bonnecaze.md @@ -0,0 +1,6 @@ +--- +title: Matthew Bonnecaze +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2022 +--- + +_coming soon_ \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2022_Thomas_Kozlowski.md b/_docs/developer/rensselaer_center_for_open_source/2022_Thomas_Kozlowski.md new file mode 100644 index 00000000..301d5de1 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2022_Thomas_Kozlowski.md @@ -0,0 +1,48 @@ +--- +title: Thomas Kozlowski +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2022 +--- + +As a first time Submitty developer, I began with familiarizing myself with the +parts of Submitty and standard procedures of development. I started out with +working on some smaller issues and feature additions, as well as reviewing +others' pull requests, which helped me get familiar with the project overall. + +Further into the summer, I worked on some late days issues for a while and then +shifted focus to learning about Docker and its use with autograding, as well as +investigating performance issues that result in incorrect grades being assigned +when grading too many assignments in parallel. + +The Docker performance is complicated and needs more work to get to a proper +solution. I mainly worked on trying to identify what causes the performance +issues and searched for ways that might help solve the problem. Ideally, it +would be great to always get the correct autograding result, but the next best +would be to provide warnings or errors to suggest fewer autograding jobs should +be run in parallel. + +### Smaller fixes and features + +- Button to demote a user from grader to student +- Fixed a bug that caused Submitty to show an error page when viewing grading +- Fixed a bug that caused the late day cache to sometimes be incorrect +- Added student registration type to grade summaries +- Added course section numbers to the Submitty homepage +- Fixed a bug that caused the late day message to be displayed incorrectly +- Fixed a bug that caused worker machine installation to fail +- Improved the container log for autograding + +### In progress work + +- Parallelizing worker machine updates +- Fixing a bug that causes the queue occupancy table to disappear +- Investigating performance issues with Docker use for grading distributed + systems assignments using multiple containers + +### Other work + +- Created a dependency graph of the Submitty installation scripts + +### Future work + +- Adding an execution logfile for autograding with additional statistics +- Further work on the performance of docker autograding diff --git a/_docs/developer/rensselaer_center_for_open_source/2023_Jaeseok_Kang.md b/_docs/developer/rensselaer_center_for_open_source/2023_Jaeseok_Kang.md new file mode 100644 index 00000000..aa16a197 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2023_Jaeseok_Kang.md @@ -0,0 +1,77 @@ +--- +title: Jaeseok Kang +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2023 +--- + +During the summer, I dedicated my efforts to a range of tasks for Submitty, including the development of new features, bug fixes, and code refactoring. + +### RainbowGrades + +Border-outline + - One of the most noticeable change made in RainbowGrades this summer + - Designed to indicate the status of individual gradeables + - Implemented primary for instructors to discern status within large table + +Git version + - Displays RainbowGrades version based on user's local repository + - Offers insight into potential discrepancies between the main and local version + - Facilitates developers to trace issues when users patch their local RainbowGrades + +Course Section ID (Course Registration Number) + - Retrieves relevant data for each student from the database and renders it into individual report JSON files + +iClicker Removal + - iClicker was tool to assist students to participate in class replaced by Submini poll + - Meticulously removed obsolete iClicker code from codebase + +Future Works + - Add version conflict status for border-outline + - Redirect compilation output to a log file + - Introduce Continuous Integration (CI) for RainbowGrades + - Apply CSS enhancements to minimize repetitive HTML code + - Refactoring the table to enable dynamical sorting, row hiding, and related improvements + + + +### Web-based customization + +Plagiarism Entries + - Instructors are now able to input plagiarism data through the web GUI + - Eliminates the need for manual editing of the customization.json file + - Web has invalid entry check, for instance, duplicate entries which has advantage over editing json file directly + - The web interface includes validation checks, such as preventing duplicates, offering an advantage over direct JSON file editing. + +Display Options + - Instructors can now choose the information to display using the web GUI + - Eliminates the need for manual editing of the customization.json file + - Description of each display option elegantly collapses with CSS updates. + +Future Works + - Switch to seamless and simultaneous saving change from manually pressing Save Change button. + - Enhance error handling, such as catching compilation errors and permission issues + + + +### Submitty_test script + +Submitty test + - A newly introduced command, similar to "submitty_install_site," runs PHP static analysis/code sniffer into a single command + - Simplify the local PHP linting process by eliminating the need to remember lengthy command lines or copy them from the website. + - This script originally started as a personal tool for myself but evolved into a valuable resource for many developers + - The decision to run it within Vagrant, despite the slower execution compared to host machines, was driven by the need for maintainability and cross-platform compatibility, prioritizing these aspects over runtime efficiency. + +Future Works +- Expand by adding JavaScript, CSS, Python linting, and Unit tests +- Ultimately, the goal is to empower developers to run most CI processes locally, reducing GitHub CI load + + + +### Database Queries + +Grading Stats + - The grading stats page now features the count of unresolved inquiries assigned to each grader + - Offer instructors to efficiently monitor and prompt the respective grader to complete their grading tasks + +Future Works + - Enhance the visual analysis and interpretation of the statistics + - Provide user-friendly tools to manipulate the statistics diff --git a/_docs/developer/rensselaer_center_for_open_source/2023_Mahi_Pasarkar.md b/_docs/developer/rensselaer_center_for_open_source/2023_Mahi_Pasarkar.md new file mode 100644 index 00000000..a753eb6e --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2023_Mahi_Pasarkar.md @@ -0,0 +1,53 @@ +--- +title: Mahi Pasarkar +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2023 +--- + +### Summary + +My work on Submitty was a great opportunity to sharpen my skills. Due to working on a large codebase and completing incomplete PRs, I improved heavily in reading code and visualizing the systems in my mind. This skill has allowed to me develop far faster than I did at the beginning of the summer, and has refined my debugging skills. I was able to work on several engaging and challenging problems, such as security, calendar overhaul, testing, and more. In addition, I worked with a wonderful team who I could always turn to to ask for help or bounce ideas off of. + +### Calendar + +My goal was to overhaul the calendar in order to make it more useful to students and instructors. +To that end, I implemented a way to focus on single classes in the calendar, in addition to seeing all at once. After that, I implemented a method to choose colors for each class. To bolster this feature, I also added a legend that +indicated what each color is for, and I chose 16 new colors (8 each for light and dark theme) that met +WAVE's accessibility guidelines for contrast. + +**Before** +![before](../../../images/RCOS_report/2023_Mahi_Pasarkar/cal-old.png) + +**After** +![after](../../../images/RCOS_report/2023_Mahi_Pasarkar/cal-new.png) +![menu](../../../images/RCOS_report/2023_Mahi_Pasarkar/cal-menu.png) + +#### Future Work + +Future features I want to add are: +* Adding course materials to calendar (in progress) +* Coloring by gradeable type (eg. Homework, Exam, etc.) +* Show unreleased gradeables on calendar +* Improved calendar mobile view + +### Sample Data + +I improved a lot of sample data to keep up with new features and refactors. I added +sample pronouns to users, sample calendar data to assist with future feature testing, +and sample forum data to include markdown. These usually required changing the way sample data is generated +in `setup_sample_courses.py`. For example, for forum data, I needed to make edits that allow posts to have +markdown enabled. For pronouns data, random pronouns needed to be assigned, which also came with the need +to change each test to conform with the new randomly generated data. + +### Testing + +I implemented and improved several Cypress end to end tests. Prior to the summer, I worked on adding pronouns to +user profiles. This feature was new and untested, so I created a comprehensive test suite for it. Additionally, I +made tests for autograder test cases, and I finished a PR that ported deprecated Selenium tests to Cypress. + +### Notebook Download Security + +Notebook gradeables are gradeables that feature problems in formats such as multiple choice, short answer, etc. +These gradeables submitted the results by recording the answer in a `txt` file. The problem with this is that the +`txt` files are visible and downloadable by the students. In most cases, it shouldn't be an issue, but if an instructor +designs the files in a way that can give a hint towards the answer it would be an unfair exploit. I edited `Access.php` to ensure that students wouldn't have permissions for the file. This way, even if students manually entered the url to +get the files, they would be prevented from accessing it. \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2023_Nia_Heermance.md b/_docs/developer/rensselaer_center_for_open_source/2023_Nia_Heermance.md new file mode 100644 index 00000000..9372eb49 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2023_Nia_Heermance.md @@ -0,0 +1,46 @@ +--- +title: Nia Heermance +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2023 +--- + +This summer, most of my work was in Course Materials, TA Grading, and site-wide refactors. + +### Course Materials + +An outstanding issue in Course Materials was the ability to hide folders from students. +You can hide a folder by setting its release date to the future, but once a folder was released, +there was now way to hide a folder's name besides a button that hid its contents. Now, when folders are hidden, +their names do not appear on the Course Materials page for students. I accomplished this through a recursive function on +the server PHP code that creates a dictionary used when rendering the page. + +While working on this issue, I found a bug where hiding one folder's contents would unintentionally hide +other folder's contents. I fixed this bug as well with additional logic. + +Another issue was the lack of folder suggestions when uploading a file or moving a file. Users would then accidentally +create a new folder rather than placing a file in an existing folder as intended. I added a list, created via server-side +PHP code and maintained by JavaScript client-side code, that provides suggested folders. + +### TA Grading + +In addition to a big project I'll discuss soon, I work on bug fixes and features throughout TA Grading. One feature I worked +on with part-time dveloper Yanli was the ability for instructors to set a default grading blindness for TAs. TAs of course +have the ability to turn off this blindness and see who they're grading, but sometimes setting the default to be unable to +see who you are grading is appropiate for the current gradeable. + +A bugfix I worked on was the blindness setting for limited access graders (i.e. undergraduate mentors) was accidentally +hiding student information for full-access graders (i.e. instructors and TAs). Worse, the limited access setting wasn't +hiding student information from the mentors themselves for team assignments! There were some small logic changes +necessary to get this setting working again. + +The main project I worked on this summer was a TA Grading refactor. Behind the scenes, TA Grading loads all of the grading +panels at once and hides the ones currently inactive. This made the page slow to boot up and also made it difficult +to expand the page to allow the panels to be popup windows. The goal of the refactor was to change the panels to be +client-side rendered so that the panels would only be loaded when necessary and student traversal wouldn't require a whole page refresh. + +Unfortunately, this refactor was my main failure of the summer. I overestimate the scope of the goal, as currently Submitty +is not set up for client-side rendering. Still, I got the grounds going for a refactor, and if I continue working on Submitty +in the future, I am confident I could continue this refactoring effort into a much faster user experience! + +### Side-wide Refactors + +The Submitty codebase has some outdated terminology. Grade Inquiries used to be called Regrade Requests, so that's what they were referred as in the code. We also used a mix of the word "semester" and the word "term" throughout when our goal is to switch to entirely the word "term" to be less confusing to schools without a semester system. These refactors were great for familiarizing myself with the codebase as I was a new Submitty developer this summer. The "semester" to "term" refactor isn't quite done, but it's getting there! \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2023_Satvik_Karanam.md b/_docs/developer/rensselaer_center_for_open_source/2023_Satvik_Karanam.md new file mode 100644 index 00000000..b2966370 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2023_Satvik_Karanam.md @@ -0,0 +1,38 @@ +--- +title: Sátvik Karanam +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2023 +--- + +During the summer of 2023, I concentrated on several major development initiatives, which are detailed below. Alongside these projects, I played a key role in developing new features, resolving bugs, reviewing over 20 pull requests, and submitting more than 25 of my own. I actively participated in daily meetings to discuss design decisions and monitor progress, working closely with a team of full-time student developers and remote contributors. + +### Porting End-to-End Tests from Selenium WebDriver to Cypress + +At the start of the summer, we had two sets of end-to-end tests, one suite written in Selenium and one in Cypress, with a sizeable overlap in their coverage. Both were configured to run as GitHub Workflows, which slowed down development. Many of the Selenium tests were heavily outdated and disabled from running at all in the cloud, and it seemed that Cypress was more convenient for development and generally more up-to-date. Hence, I started the long-term goal of porting all existing Selenium tests over to Cypress, writing up issue [Submitty#9335](https://github.com/Submitty/Submitty/issues/9335) to organize and facilitate this. I proceeded with porting the W3 accessibility test, which involved rewriting a Python script into JavaScript code while keeping the Java dependency intact. + +### Multi-worker HashiCorp Vagrant Setup + +In a production environment, Submitty uses separate worker machines to which it delegates autograding jobs. For testing and developing this functionality, it is necessary for developers to be able to run virtual machines on their development machine to act as workers. With the existing setup, it was possible to run one worker machine alongside the main VM, but in order to develop new features such as parallelizing worker updates, it became necessary to be able to launch multiple worker VMs in a development environment. So in [Submitty#9537](https://github.com/Submitty/Submitty/pull/9537), I refactored the existing system for configuring worker machines and added functionality to create multiple worker VMs simultaneously alongside the main development VM. This involved updating shell scripts, configuration files, and writing Python scripts to facilitate the new setup + +### Refactoring PostgreSQL Trigger Functions into Version-Controlled Files to Enhance Maintainability + +In the existing migration system for Submitty, any migration that modified a PostgreSQL database trigger function needed to copy the entire body of the function into the migration code and then make alterations to it. This made it difficult to recognize the code changes to the function body in reviews, and to track the history of these changes as well. After discussing possible solutions, it was decided that it would be best to store the trigger functions in separate files and write Python scripts to load them in separately on migrations, which I implemented as part of [Submitty#9452](https://github.com/Submitty/Submitty/pull/9452). + +### Automating Repository Release Updates with GitHub Actions + +The main Submitty repository depends on several other repositories maintained separately, including Lichen, RainbowGrades, AnalysisTools, and Localization. Previously, making a new release in one of these repositories meant that the pinned version in the Submitty repository needed to be updated manually, which was difficult to manage as all other dependencies were handled automatically through Dependabot. As part of [Submitty#9495](https://github.com/Submitty/Submitty/pull/9495), I created a system to automate the sending of release updates to the main Submitty repository using Python scripts and GitHub Actions. + +### Refactoring JavaScript Cookies + +After years of development by generations of students, Submitty’s frontend was comprised of a ton of JavaScript code, both in script files and embedded into Twig documents. There were numerous coding styles and design patterns used across different areas of the client side code, one example being methods for retrieving and storing data in cookies. While some files used a long regular expression that was duplicated on each line for retrieving a cookie, others defined their own functions for getting and setting cookies. Through [Submitty#9314](https://github.com/Submitty/Submitty/pull/9314), I refactored the frontend to consolidate the usage of cookies across all JavaScript code on Submitty using a third-party library that was imported into each file. This ensured that whenever code needed to read or write cookies, its behavior would be predictable and consistent with the rest of the site. + +Furthermore, many areas of the site used cookies in a disorganized and error-prone way, the most problematic instance being present on the Course Materials page, where cookies were used to track the state of the file tree (i.e. which directories are expanded and collapsed). For this, separate cookies were created with URL encoded paths of each directory, which significantly polluted the namespace. With [Submitty#9404](https://github.com/Submitty/Submitty/pull/9404), I refactored this logic such that all file tree data was stored in a single cookie, which cleaned up a lot of the clutter in Submitty’s cookie storage. + + +### Localization of Submitty + +Wrapping up this summer, I took on the task of finishing up a longer-term goal I had started in the spring, which was the creation of a system to localize Submitty’s frontend. This would allow different users to view and interact with the website in various languages other than English. + +The largest component of this system was developed in [Submitty#9079](https://github.com/Submitty/Submitty/pull/9079). This included methods for displaying text in Twig templates as language keys rather than simple plaintext. With this, the sysadmin could now choose a different language for their Submitty instance to use, with all untranslated strings falling back to the “English (US)” locale. The idea was that this would lay the groundwork for schools in foreign countries with non English-speaking students and staff to use Submitty as well, once enough users submitted translations for their language. Most of the challenges on this PR were related to designing the system while keeping in mind several issues such as performance, ease of translation, ease of future development, etc. The design went through several iterations since May before finally settling on the current system which was merged in August. + +Another component which was being developed in parallel was the ability for users to set a language different from the site’s default in their accounts. This would allow for students who are more comfortable in a different language from the one chosen by their school to access Submitty in the most convenient way for them. This functionality was developed in [Submitty#9415](https://github.com/Submitty/Submitty/pull/9415) and merged shortly after the previous localization PR. + diff --git a/_docs/developer/rensselaer_center_for_open_source/2023_Viane_Matsibekker.md b/_docs/developer/rensselaer_center_for_open_source/2023_Viane_Matsibekker.md new file mode 100644 index 00000000..85ac811c --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2023_Viane_Matsibekker.md @@ -0,0 +1,6 @@ +--- +title: Viane Matsibekker +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2023 +--- + +_coming soon_ \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2023_Youssef_Hassan.md b/_docs/developer/rensselaer_center_for_open_source/2023_Youssef_Hassan.md new file mode 100644 index 00000000..d0c416cc --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2023_Youssef_Hassan.md @@ -0,0 +1,46 @@ +--- +title: Youssef Hassan +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2023 +--- + +During the summer of 2023, I had my first experience contributing to open-source. I dedicated myself to completing pending features, introducing new functionalities, and resolving bugs in Submitty. While doing so, I also actively reviewed the work of my fellow team members, which helped us all work together effectively to enhance the user experience. Additionally, I actively participated in the development process by submitting bug reports on Github and proposing ideas for implementation. I am looking forward to addressing these suggestions in the upcoming months, further contributing to the improvement of Submitty. + +### Completing pending features + +* One of the initial tasks I undertook was the implementation of counters within the office hours queue. This addition helps instructors, mentors, and teacher assistants understand how frequently students use the queue, allowing them to provide assistance more efficiently, especially to those who received less help. + +* On the grading index page, an adjustment was implemented for graders. Instead of the previous blue 'Grade' button used for both on-time and too late submissions, a red button labeled "Too Many Late Days" has been introduced. This modification ensures that TAs are informed about the status prior to accessing the student's submission, helping them grade with better information. + +* Another contribution was the implementation of a new modal on the grading statistics page, which offers users the option to apply filters that include or omit specific submissions. These filters cover overridden submissions, bad submissions (excessive late day use), and submissions within the NULL registration section (which include dropouts and designated graders). The filters impact statistics for student submissions, progress in TA grading, manually and autograded submissions. +Using these filters carefully resolves statistical irregularities caused by late submissions and changes in the NULL registration section, ensuring accurate representation. + +* The last task I undertook was the integration of Cypress End-to-End tests for Submitty. These tests carefully assess changes in gradeable information, late days and extentions usage, and late submissions. This analysis also ensures that the changes are accurately reflected both from the perspective of student submissions and within the late day cache, a table within the database. This involved replacing the previous late days forensic page and refactoring it into the Bulk Late Day Usage page, which only instructors can access. This new interface represents the late day cache, giving instructors the choice to populate entries or clear the table as needed. + +### Introducing Improvements + +* To complement the filters added in the grading statistics page, I introduced additional Cypress End-to-End tests that use the filters to ensure that the displayed statistics align with the expected values. + +* I modified the display names used by instructors and graders when addressing grade inquiries. + +* Further, I introduced a new setting into the profile page, allowing for customizable sidebar display options. This setting offers users the choice to show only icons on narrow screens or to keep the sidebar expanded at all times. This adjustment addresses the previous issue where the sidebar would inconveniently collapse on narrower screens. + +* With valuable assistance from Barbara Cutler, I introduced the initial version of documentation that guides new developers and contributors in translating pages within Submitty. + +* Furthermore, utilizing code previously implemented by fellow contributor Sátvik Karanam, I contributed to the translation of Submitty's profile page into French. This marked the first translation beyond English in Submitty's supported languages. + +* I enhanced the documentation to assist future contributors in addressing challenges I encountered, including troubleshooting the installation of a virtual machine using Vagrant and resolving issues related to generating and viewing Submitty webpages. + + +### Implementing Bugfixes + +* I refactored the code responsible for displaying warning messages before late submissions because I discovered some inconsistencies. Previously, incorrect messages or no messages would appear due to the logic used to display the messages or the code inaccurately assessing the time against the deadline, which potentially misled students. The new code carefully addresses edge cases and eliminates the need to reload the submission portal after the due date has passed. This enables timely display of warning messages directly after the deadline, facilitated by a Javascript timer synchronizing with the server periodically. + +* I identified and resolved an issue with a Submitty page that was causing excessive queries by adding it to the ignore list. Moving forward, the plan is to refactor the queries that are executed iteratively and combine them into a single larger query. + +* I located and removed a duplicated faulty page that was appearing. + +* I resolved an issue that prevented instructors from downloading student submissions. + +### Acknowledgments + +* I would like to express my gratitude to Barbara Cutler and my fellow contributors during the summer for their assistance and guidance when I encountered challenges. I greatly appreciate the opportunity to work on Submitty during the summer. diff --git a/_docs/developer/rensselaer_center_for_open_source/2024_Dorian_Bilelis.md b/_docs/developer/rensselaer_center_for_open_source/2024_Dorian_Bilelis.md new file mode 100644 index 00000000..268502df --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2024_Dorian_Bilelis.md @@ -0,0 +1,6 @@ +--- +title: Dorian Bilelis +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2024 +--- + +coming soon \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2024_Jaeseok_Kang.md b/_docs/developer/rensselaer_center_for_open_source/2024_Jaeseok_Kang.md new file mode 100644 index 00000000..1cabf996 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2024_Jaeseok_Kang.md @@ -0,0 +1,6 @@ +--- +title: Jaeseok Kang +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2024 +--- + +coming soon \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2024_Michael_Papadopoulos.md b/_docs/developer/rensselaer_center_for_open_source/2024_Michael_Papadopoulos.md new file mode 100644 index 00000000..469bd9b1 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2024_Michael_Papadopoulos.md @@ -0,0 +1,34 @@ +--- +title: Michael Papadopoulos +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2024 +--- + +This summer, my primary goal was to get Submitty to a state where it could be used for courses on Quantum Computing. I also did substantial work on Autograding. + +### Quantum Computing + +- Built a qiskit-capable docker image for use with Submitty +- Created various autograding examples and learning materials for professor and course use. Here are the publicly available ones: + - [Qiskit Circuit Draw Diff](https://github.com/Submitty/Submitty/tree/main/more_autograding_examples/qiskit_circuit_draw_diff) + - [Qiskit Tolerance Diff](https://github.com/Submitty/Submitty/tree/main/more_autograding_examples/qiskit_tolerance_diff) +- Worked on Submitty's ability to connect to the internet during grading so it can contact IBMQ cloud services. Added an autograding example for this. + - [Networking](https://github.com/Submitty/Submitty/tree/main/more_autograding_examples/networking) +- Developed a lab for an ongoing quantum computing course which was graded through Submitty. + +### Autograding + +- Added buildtime errors when a required capability doesn't exist or an image isn't on the required capability. +- Fixed tolerance grading to work with various nonstandard formattings. +- Heavily updated documentation on the `config.json` file +- Reworked various old autograding examples to use Docker for security. + +### Miscellaneous & Future + +- Upgraded Grade Overrides such that an instructor can override a whole team at once. +- Improved student management to allow students to rejoin courses they dropped and notify instructors of students who dropped. +- Improved the notebook interface to work well with "short-response" answers. +- Changed the forum search feature to be more accurate and useful, especially in regards to filenames. +- Improved various end-to-end Cypress tests by removing flaky code. +- Updated the `pdf-annotate.js` library to use a more secure version of `pdf.js`. +- Allow students to select their preferred name order in the Profile page. +- Various fixes to typos, spacing, and CSS across the site. diff --git a/_docs/developer/rensselaer_center_for_open_source/2024_William_Powe.md b/_docs/developer/rensselaer_center_for_open_source/2024_William_Powe.md new file mode 100644 index 00000000..61b554de --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2024_William_Powe.md @@ -0,0 +1,6 @@ +--- +title: William Powe +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2024 +--- + +coming soon \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2024_Zachary_Niles_Peretz.md b/_docs/developer/rensselaer_center_for_open_source/2024_Zachary_Niles_Peretz.md new file mode 100644 index 00000000..2c352e2d --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2024_Zachary_Niles_Peretz.md @@ -0,0 +1,33 @@ +--- +title: Zachary Niles Peretz +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2024 +--- + +While I completed tasks across Submitty, I primarily focused on expanding the Rainbow Grades GUI Customization Menu so that it would become more widely used by professors. I implemented several features to the menu so that it could match the capabilities of manual JSON configuration, improved the user interface experience, added testing, and fixed bugs. + +My work includes, but is not limited to, the following items: + +## Rainbow Grades Web-Based Customization +#### Features Implemented + - Adjusting final grade cutoffs (PR [#10518](https://github.com/Submitty/Submitty/pull/10518)) + - Manual grading of specific students (PR [#10653](https://github.com/Submitty/Submitty/pull/10653)) + ![FinalAndManualGrades](../../../images/RCOS_report/2024_Zachary_Niles_Peretz/FinalGradeCutoffsAndManualGrading.png) + - Grading assignments by configurable percents instead of by score (PR [#10763](https://github.com/Submitty/Submitty/pull/10763)) + ![FinalAndManualGrades](../../../images/RCOS_report/2024_Zachary_Niles_Peretz/PerGradeablePercents.png) + - Setting automatic academic performance warning benchmarks (PR [#10859](https://github.com/Submitty/Submitty/pull/10859)) +#### Improvements + - Testing Web-Based Customization functionality (PR [#10726](https://github.com/Submitty/Submitty/pull/10726)) + - Testing and improving Web-Based Customization accessibility (PR [#10515](https://github.com/Submitty/Submitty/pull/10515)) + - Toggling visibility of configurables based on the state of associated checkboxes (PR [#10593](https://github.com/Submitty/Submitty/pull/10593)) + - Removing unused checkboxes (PR [#10644](https://github.com/Submitty/Submitty/pull/10644)) + + +## Polls + - Allowing students to submit custom options on specified polls (PR [#10197](https://github.com/Submitty/Submitty/pull/10197)) + - Allowing display of a poll timer to students and instructors (PR [#10337](https://github.com/Submitty/Submitty/pull/10337)) + + +## Office Hours Queue + - Using switches instead of buttons for notifications (PR [#10564](https://github.com/Submitty/Submitty/pull/10564)) + ![FinalAndManualGrades](../../../images/RCOS_report/2024_Zachary_Niles_Peretz/NotificationSwitches.png) + - Refactoring alert noise and replacing audio something more in line with Submitty’s theme (PR [#10555](https://github.com/Submitty/Submitty/pull/10555)) diff --git a/_docs/developer/rensselaer_center_for_open_source/2024_Zheyu_Deng.md b/_docs/developer/rensselaer_center_for_open_source/2024_Zheyu_Deng.md new file mode 100644 index 00000000..80c6d666 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2024_Zheyu_Deng.md @@ -0,0 +1,6 @@ +--- +title: Zheyu Deng +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2024 +--- + +coming soon \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2025_Alexander_Lavallee.md b/_docs/developer/rensselaer_center_for_open_source/2025_Alexander_Lavallee.md new file mode 100644 index 00000000..405db122 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2025_Alexander_Lavallee.md @@ -0,0 +1,19 @@ +--- +title: Alexander Lavallee +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2025 +--- + +While there were many things I did during the summer, there are two main projects I worked on. + +## Bulk Upload Redactions + +Previously, when an exam was uploaded to a gradeable with anonymous grading enabled, graders would frequently still be able to see the student names on the uploaded files. During this summer I worked on a feature that automatically redacts instructor-specified regions of the uploaded files, hiding all sensitive information from the graders. This involved adding a configuration item for instructors to specify the regions to redact, and edits to our job queue system to handle the redaction and re-redaction processes. + +![Configuration](/images/start_redactions.png) + +![Bulk Upload Redactions](/images/redacted.png){: style="width:45%;vertical-align:top"} +![Unredacted](/images/unredacted.png){: style="width:45%;vertical-align:top"} + +## Integrating Vue.js + +In addition to the redaction feature, I also created a new Twig component that allows for the rendering of Vue.js components within the Submitty framework. This allowed us to start moving components to a more modern JavaScript framework, improving the overall user experience and maintainability of the codebase. Some examples of components that were migrated include the homepage, sidebar, and parts of the TAGrading interface. This has made it easier to develop and maintain the frontend code, which is especially important for a student-developed project like Submitty. diff --git a/_docs/developer/rensselaer_center_for_open_source/2025_Christopher_Poon.md b/_docs/developer/rensselaer_center_for_open_source/2025_Christopher_Poon.md new file mode 100644 index 00000000..ed076fad --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2025_Christopher_Poon.md @@ -0,0 +1,42 @@ +--- +title: Christopher Poon +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2025 +--- + +As a first-time Submitty developer, I focused on significantly expanding its quantum computing capabilities and strengthening its core autograding infrastructure. My primary achievement was engineering a secure and robust system for autograding Jupyter Notebooks, a critical feature for modern computational courses. Additionally, I enhanced platform stability and instructor experience by resolving outstanding issues and refactoring key Docker functionalities. My contributions are reflected in over 25 pull requests and more than 20 peer reviews. + +### Quantum Computing Integration + +This term, I built upon Submitty's existing quantum computing foundation to support more advanced, interactive coursework. I began development of new course content, including a foundational prerequisite course designed to onboard students with the necessary background in linear algebra, complex numbers, and core principles of quantum physics. Building on that, I designed a hands-on lab for Simon's algorithm to demonstrate one of the first known exponential speedups over classical computation. To ensure compatibility with modern tools, I upgraded the Qiskit Docker image to version 2.0.1. I also began work autograding quantum teleportation across a network. + +![](../../../images/RCOS_report/2025_Christopher_Poon/simons.png) + +![](../../../images/RCOS_report/2025_Christopher_Poon/complex_numbers.png) + +To support this advanced coursework, I engineered a secure autograding pipeline for Jupyter Notebooks ([PR#11736](https://github.com/Submitty/Submitty/pull/11736), [PR#11862](https://github.com/Submitty/Submitty/pull/11862), [PR#11917](https://github.com/Submitty/Submitty/pull/11917)). This feature enables precise grading of individual cells and uses notebook metadata to conceal autograding logic from students. I also integrated in-browser notebook rendering ([PR#11891](https://github.com/Submitty/Submitty/pull/11891)), allowing students to view assignments directly on the platform for feedback. + +![](../../../images/RCOS_report/2025_Christopher_Poon/simons_checkpoint4.png) + +These improvements strengthen the existing foundation for quantum computing integration within Submitty, while also benefiting other fields that rely on Jupyter Notebooks—particularly data science. + +### Autograding & Docker + +I took ownership of key improvements to Submitty's containerized autograding infrastructure, with a focus on stability, usability, and maintainability. I shepherded the final stages of a major Docker UI refactor ([PR#11120](https://github.com/Submitty/Submitty/pull/11120)) by resolving lingering bugs, fixing type mismatches, and linting issues. I then contributed several enhancements, including bug fixes and the addition of UI status buttons ([PR#11739](https://github.com/Submitty/Submitty/pull/11739), [PR#11804](https://github.com/Submitty/Submitty/pull/11804), [PR#11883](https://github.com/Submitty/Submitty/pull/11883)). + +![](../../../images/RCOS_report/2025_Christopher_Poon/docker_ui.png) + +On the backend, I extended Docker functionality by adding build-time error detection and the ability to remove images by ID ([PR#10839](https://github.com/Submitty/Submitty/pull/10839), [PR#11357](https://github.com/Submitty/Submitty/pull/11357)). Previously, Submitty only supported image removal on the primary machine, resulting in wasted storage on worker machines where images were left behind. I resolved this by extending image removal support to worker machines ([PR#11812](https://github.com/Submitty/Submitty/pull/11812)), updating Cypress tests as needed. To improve reliability, I fixed critical bugs across the container system and improved error messaging for developers and instructors ([PR#9710](https://github.com/Submitty/Submitty/pull/9710), [PR#11697](https://github.com/Submitty/Submitty/pull/11697), [PR#11717](https://github.com/Submitty/Submitty/pull/11717), [PR#11744](https://github.com/Submitty/Submitty/pull/11744)). + +![](../../../images/RCOS_report/2025_Christopher_Poon/build_failure.png) + +![](../../../images/RCOS_report/2025_Christopher_Poon/gradeable_failure.png) + +### Miscellaneous & Future Work + +In addition to working on integrating quantum computing with Submitty, I contributed to a range of platform improvements and participated in code reviews to maintain project quality. + +Next steps for quantum computing integration include: + +- Expanding both prerequisite course content and prospective course labs and homeworks +- Embedding Jupyter autograding natively into Submitty (removing reliance on scripts) +- Enabling student quantum circuits to run via a Submitty-managed IBM Quantum account \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2025_Giancarlo_Martinelli.md b/_docs/developer/rensselaer_center_for_open_source/2025_Giancarlo_Martinelli.md new file mode 100644 index 00000000..9a47e04e --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2025_Giancarlo_Martinelli.md @@ -0,0 +1,28 @@ +--- +title: Giancarlo Martinelli +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2025 +--- + +This summer I primarily worked on two new Submitty features, live chat and image annotation. + +## Live Chat + +Going into the summer, [Live Chat](https://github.com/Submitty/Submitty/pull/10214) was functional but needed security updates and some style fixes, so the first thing I did when starting work on Submitty was move the websocket from the client to the server, updated the style of the Live Chat, and added websocket chatroom enables and disables: + +![Live Chat Demo](../../../images/RCOS_report/2025_Giancarlo_Martinelli/chatroomdemo.gif) + +Additionally, I wrote [end to end tests](https://github.com/Submitty/Submitty/pull/11818) for the new feature, including a proof of concept for end to end websocket testing using Cypress, which we previously thought might require a different testing library. This was done with the immense help of [Jeffrey Cordero](/developer/rensselaer_center_for_open_source/2025_Jeffrey_Cordero) who implemented this new testing pattern for many other features this summer. + +## Image Annotation + +During the summer one of our group's main goals was to get the number of open pull requests down to 0 by the end of the summer. One large thing preventing that were our open dependency PRs, one of which was a [double dependency of PDF annotator and PDF rendering](https://github.com/Submitty/Submitty/pull/11013). While I was able to update the PDF rendering dependency with some help from the other members we were unable to update our PDF annotator dependency because the package was maintained solely by Submitty, and wasn't even working in its most recent release. That realization led to the decision to remove the PDF annotation feature in favor of an image annotation feature. This coincided well with the addition of bulk upload, which turns large PDFs into a series of images. The idea is that in the future we'll stitch these images back together into a PDF-like format. As part of that I wrote a new [image annotation](https://github.com/Submitty/Submitty/pull/11921) implementation using a library [markerJS](https://markerjs.com/) which works really well as a plug-and-play solution to the problem. The relative age of our tech stack made this a little more difficult but I was eventually able to implement image annotation: + +![Live Chat Demo](../../../images/RCOS_report/2025_Giancarlo_Martinelli/imageannotationdemo.gif) + +## Urgent Bugfixes + +I made two urgent fixes to our i[nstall site script](https://github.com/Submitty/Submitty/pull/11854) and [course materials](https://github.com/Submitty/Submitty/pull/11909). The install site script had been broken inadvertently by changes to our overall install script, and I was able to fix the script with the help of my peers. The course materials bug was a bug that was discovered this summer but had existed previously, we investigated the cause of the bug and I was able to identify and fix it, along with fixing a lot of other related bugs in course materials, meaning that the feature will be more stable and predictable than it was previously. Not only is bugged input prevented, but it also should fail more gracefully if bugged input is somehow accepted. + +## Other to Mention + +Finally, I helped draft out [first PR autoreply](https://github.com/Submitty/Submitty/pull/11597) script/text, which allows us to more efficiently interact with new developers. \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/2025_Jeffrey_Cordero.md b/_docs/developer/rensselaer_center_for_open_source/2025_Jeffrey_Cordero.md new file mode 100644 index 00000000..4fe753c4 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2025_Jeffrey_Cordero.md @@ -0,0 +1,71 @@ +--- +title: Jeffrey Cordero +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2025 +--- + +During my time with Submitty, I was a key contributor to the open-source academic platform, working on full-stack development, infrastructure modernization, and system security. My core contributions included enhancements to Notifications, Rainbow Grades, WebSockets, CI/CD improvements, and various bug fixes. I also participated extensively in pull request reviews across the entire tech stack, which deepened my experience with collaborative development, engaging in design discussions, reviewing code at scale, and promoting practices that emphasize maintainability and reliability. The following sections highlight some of the most interesting features I had the opportunity to build this summer. + +### Notification System Enhancements + +To improve student communication, I implemented significant enhancements to Submitty’s notification system. These included automatic in-platform and email alerts when grades are released ([#10358](https://github.com/Submitty/Submitty/pull/10358)) and when new assignments become available ([#11897](https://github.com/Submitty/Submitty/pull/11897)). A reliable hourly cron job now ensures the timely delivery of these messages across all active courses. + +``` +[Submitty sample] Grade Released: Grading Homework PDF +Your grade is now available for Grades Released Homework in course +SAMPLE. + +Click here for more info: http://localhost:1511/courses/s25/sample/gradeable/grading_homework_pdf + +-- +NOTE: This is an automated email notification, which is unable to receive replies. +Please refer to the course syllabus for contact information for your teaching staff. +Update your email notification settings for this course here: http://localhost:1511/courses/s25/sample/notifications/settings +``` + +To support these improvements, I also built dedicated Cypress test suites for email delivery ([#11878](https://github.com/Submitty/Submitty/pull/11878)) and notification preferences ([#11913](https://github.com/Submitty/Submitty/pull/11913)). These tests lay the foundation for more robust future testing of the notification system. + +
+ Cypress Notification Testing +
+ +### Rainbow Grades Nightly Build + +Previously, the Rainbow Grades summary page could become outdated unless instructors manually triggered a rebuild. To streamline this process, I enhanced the nightly summary generation script to automatically trigger the build process before generating new summaries ([#11496](https://github.com/Submitty/Submitty/pull/11496)). As a result, students now have continuous access to up-to-date grade reports each day. + +```bash +$ python3 sbin/generate_grade_summaries.py f25 sample submitty_daemon +Successfully selected the manual customization for f25.sample +Successfully submitted the Rainbow Grades build process for f25.sample +Successfully completed the Rainbow Grades build process for f25.sample +Successfully generated grade summaries for f25.sample +``` + +
+ Rainbow Grades Nightly Build +
+ +### WebSocket Security & Testing + +I addressed a critical security flaw in the platform's WebSocket server by implementing a token-based authorization system ([#11634](https://github.com/Submitty/Submitty/pull/11634)). Previously, any user with a direct URL and valid login credentials could access any WebSocket page, posing a considerable risk for real-time student-instructor communications. + +To mitigate this, I designed a JSON Web Token (JWT)–based authorization layer. The web server now generates short-lived, multi-use tokens scoped to specific pages. These tokens ensure WebSocket connections are established only by authorized users with access managed through a sliding window mechanism that gracefully handles expired pages, reducing the average WebSocket authentication time by approximately 90%. + +```json +{ + "iat": 1753797357.504631, + "iss": "https://submitty.org/", + "sub": "instructor", + "authorized_pages": { + "f25-sample-defaults": 1753800957, + "f25-sample-chatrooms-1": 1753800957, + "f25-sample-polls-3-instructor": 1753800912 + }, + "expire_time": 1753800957 +} +``` + +Alongside these changes, I introduced the platform’s first end-to-end WebSocket test suite in the Discussion Forum ([#11873](https://github.com/Submitty/Submitty/pull/11873)), which was part of a broader testing strategy including new PHP unit tests for backend logic and Cypress end-to-end tests to verify secure, token-based WebSocket connections. + +
+ Cypress WebSocket Testing +
diff --git a/_docs/developer/rensselaer_center_for_open_source/2025_Justin_Manion.md b/_docs/developer/rensselaer_center_for_open_source/2025_Justin_Manion.md new file mode 100644 index 00000000..f2605063 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2025_Justin_Manion.md @@ -0,0 +1,118 @@ +--- +title: Justin Manion +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2025 +--- + +[View my commits](https://github.com/Submitty/Submitty/commits?author=JManion32) + +**54** pull requests reviewed +**29** pull requests created +**16** pull requests taken over and merged + +Spending Summer 2025 as a full time Submitty developer was a unique and incredibly rewarding experience! Here are some of the features I worked on: +### Displaying all Notifications on the Home Page +Submitty previously only displayed notifications on a per-course basis, meaning users had to visit each individual course to view or mark notifications as read. As we’ve added more advanced notification features, this limitation became increasingly cumbersome, especially for users in multiple courses. On top of that, the home page itself felt bare, with lots of unused space. + +#### Initial PR ([#11914](https://github.com/Submitty/Submitty/pull/11914)) + +**Design Process** +Since this feature is now front and center on the site, thoughtful UI/UX design was essential. We started with whiteboard sketches to explore layout ideas, then moved to Figma to create a polished mockup for feedback and iteration. Throughout development, I regularly demoed progress to the group to gather input and refine both functionality and design. + +**Technical Challenges** +The main challenge was efficiently aggregating notifications from multiple course databases. Since each course requires its own query and this feature now runs every time a user visits the home page, performance was crucial. To address this, I optimized the process by: +- Limiting queries to only active courses +- Limiting each query to the 10 most recent notifications +- Sorting results server-side for efficiency +- Creating a new database index on `created_at` and `to_user_id`, reducing the time complexity from **O(courses × notifications)** to **O(courses)** + +#### Mark as Seen ([#12007](https://github.com/Submitty/Submitty/pull/12007)) +After the original feature was merged, it quickly became clear that users needed a way to dismiss unseen notifications without being redirected. This PR adds an envelope icon next to each unseen notification, allowing them to be marked as seen in place. + +#### Improve Interactivity ([#12012](https://github.com/Submitty/Submitty/pull/12012)) +As mentioned above, it’s critical that this feature has a clean and intuitive UI. This PR improves the design with the following changes: +- Added a star icon next to gradeable notifications. +- Increased the font weight of notification content for better readability. +- Linked each notification’s course name to that course’s notifications page. +- Refactored click behavior: with three clickable elements in each container, only the individual elements are now clickable (rather than the entire container). +Each element also underlines on hover. This design is inspired by GitHub Actions' job design: +image + +#### The Final Product +![](/images/home_page_notifications.png) + +This update not only streamlines how users interact with notifications, but also transforms the homepage into a more dynamic and informative landing experience. Looking ahead, +I hope to expand this space further by adding upcoming gradeables, grade summaries, and other personalized insights to evolve the homepage into a true dashboard. + + +### Gradeable Configuration Text Editor +Historically, editing a gradeable’s configuration in Submitty required switching to a different server directory, uploading a full config bundle, or using the limited Notebook Builder tool. There was no support for directly editing config.json or supplemental files from the web interface. + +**Gradeable Config Editor ([PR#10325](https://github.com/Submitty/Submitty/pull/10325))** +I inherited this PR from [Tate Whiteberg](https://github.com/DarthNyan) and completed the implementation of the initial text editor for editing gradeable configuration files. + +**Live Editing with CodeMirror ([PR#11814](https://github.com/Submitty/Submitty/pull/11814))** +Rather than just using a basic text area, I implemented Code Mirror to allow for a more customizable experience, and native tab support. + +**File & Folder Management ([PR#11860](https://github.com/Submitty/Submitty/pull/11860))** +Added UI components to allow adding and deleting files and directories from the gradeable configuration. + +**Customizable Environment ([PR#11924](https://github.com/Submitty/Submitty/pull/11924))** +Took advantages of Code Mirror's features by adding toggles for line numbers and tab size. + +**Download Config as ZIP ([PR#11973](https://github.com/Submitty/Submitty/pull/11973))** +Added a button to download the entire config directory as a ZIP archive, allowing users to save edits they made on the site editor for future use. + +**Design & UX Polish ([PR#11991](https://github.com/Submitty/Submitty/pull/11991) and [PR#12003](https://github.com/Submitty/Submitty/pull/12003))** +Refined visual layout and interactions to feel intuitive and consistent with the rest of Submitty. Changes include highlighting selected files, adding tool tips to the customize toggles, smoothing out the transition between text files, ensuring correct file order (root-level directories first, then root-level files), and improving overall spacing for readability. + +**Edit Directory File (Coming Soon)** +Allows users who pull from Submitty's private course repository to use the gradeable config editor. Before I can create this, there is a security vulnerability that must to be addressed. Currently, there are no checks to ensure that the user pulling from the repository owns the file. This means that anyone with SSH access would be able to edit any autograding configuration on the web app. + +**Documentation ([PR#707](https://github.com/Submitty/submitty.github.io/pull/707))** +View documentation page [here](https://submitty.org/instructor/assignment_configuration/configuration_editor). + +![](/images/gradeable_config_editor.png) + +### Dark Mode Toggle for the Documentation Site +[PR#691](https://github.com/Submitty/submitty.github.io/pull/691) +To improve accessibility and match user expectations, I added a dark mode toggle to the Submitty documentation site. The site is built with Jekyll and uses auto-generated styles, so integrating theme switching required working around those constraints. + +**Implementation:** +- **SCSS Theming** – Introduced a dedicated `_colors.scss` file to define color variables for both light and dark themes. These variables are applied across components to ensure consistency and maintainability. +- **Style Overrides** – Since the site uses a mix of default and third-party CSS, I selectively overrode conflicting styles via `dark_mode.css` to support dark mode without breaking layout or readability. +- **JavaScript Toggle** – Implemented a lightweight JS toggle that saves user preference and dynamically applies the appropriate theme class. +- **Responsive Design** – Tested and refined the toggle to ensure it works seamlessly across devices, including mobile. All elements have a `0.2s` transition time for a smooth, polished theme change. + +![alt text](image.png) + +### Additional Work: +**Filter Withdrawn Students ([PR#11792](https://github.com/Submitty/submitty.github.io/pull/11792))** +Initially created by GitHub user [yanliw123](https://github.com/yanliw123). To streamline grading, this PR adds a toggle that hides withdrawn students from the grading page, so TAs can focus only on active students. + +**Add Audit / Withdrawn to Sample Data ([PR#11882](https://github.com/Submitty/submitty.github.io/pull/11882))** +Added two students with registration_type set to `withdrawn` and two with `audit` to the existing sample data, which uses a seeded random number generator. Modifying this data shifted all related values, requiring updates to 20+ Cypress test files to ensure the feature could be integrated. + +**Team Grade Override ([PR#10677](https://github.com/Submitty/submitty.github.io/pull/10677))** +Initially created by [Michael Papadopoulos](https://submitty.org/developer/rensselaer_center_for_open_source/2024_Michael_Papadopoulos). When overriding a grade in a team gradeable, instructors would have to process each student individually. Now, a popup listing the student’s teammates displays, notifying the instructor that they have teammates, and asking if they want to override them as well. + +### Reflection +This summer significantly expanded my skill set as a developer, with clear progress reflected in my pull requests. What began as simple frontend styling tweaks quickly grew into the implementation of complex, full-stack features spanning multiple layers of the system. I’m excited to keep pushing my skills further and exploring new challenges ahead! + +Working on Submitty felt a lot like being part of a fast-moving startup, where everyone contributes meaningfully, pushes large commits daily, and solves real problems that impact real users. I genuinely believe this experience has been just as valuable as, if not more than, a traditional internship. The open source nature of the project meant that I got out of it what I put in. I’m proud of what I’ve built this summer, and more importantly, I feel prepared to take on real-world engineering challenges. + + +### Future Plans for Submitty +I am planning to work on Submitty in Fall 2025 and Spring 2026 (and beyond!). Here are some features I am interested in adding: + +- **Mentor new developers** – Having experienced the challenge of learning Submitty’s large codebase as a newcomer, I’m eager to share my knowledge and help new contributors get up to speed quickly while enjoying the process along the way. +- **Enhance the Autograding Configuration page** – A vital tool for instructors; improving it means a better experience for everyone. +- **Transform the home page into a dashboard** – Adding notifications was a good start, but there is more information to centralize such as grade summaries and upcoming gradeables. +- **Refactor and modularize `forum.js`** – The forum is a favorite feature but most of its JavaScript is in a single 3,000 line file. Breaking it up will make it cleaner, faster, and easier to improve. +- **Improve site intuitiveness and maintainability** – Tackle tech debt with cleaner CSS, fewer inline scripts, smaller files, and stronger testing, making the platform friendlier for all developers. +- **Convert more pages to Vue** – The component-based approach is a joy to work with and a strong candidate to become a core part of the stack. +- **Work with the database** – I'm taking Database Systems next semester, and am excited to apply what I learned to Submitty! +- **Explore WebSockets** – I still haven't worked with them much, and want to learn more! + +-- + +Overall, this summer has been an invaluable experience in my journey to becoming a real-world software developer. I would like to thank Professor Cutler, my teammates, and RPI for making this happen. I’m so proud of all that we accomplished and excited to see what we create next! diff --git a/_docs/developer/rensselaer_center_for_open_source/2025_Williams_Chen.md b/_docs/developer/rensselaer_center_for_open_source/2025_Williams_Chen.md new file mode 100644 index 00000000..55b8fb13 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/2025_Williams_Chen.md @@ -0,0 +1,6 @@ +--- +title: Williams Chen +category: Developer > Rensselaer Center for Open Source (RCOS) > Summer 2025 +--- + +coming soon \ No newline at end of file diff --git a/_docs/developer/rensselaer_center_for_open_source/image-2.png b/_docs/developer/rensselaer_center_for_open_source/image-2.png new file mode 100644 index 00000000..69d9b12e Binary files /dev/null and b/_docs/developer/rensselaer_center_for_open_source/image-2.png differ diff --git a/_docs/developer/rensselaer_center_for_open_source/image.png b/_docs/developer/rensselaer_center_for_open_source/image.png new file mode 100644 index 00000000..a5f8d50c Binary files /dev/null and b/_docs/developer/rensselaer_center_for_open_source/image.png differ diff --git a/_docs/developer/rensselaer_center_for_open_source/moorthy.md b/_docs/developer/rensselaer_center_for_open_source/moorthy.md new file mode 100644 index 00000000..a34a61b5 --- /dev/null +++ b/_docs/developer/rensselaer_center_for_open_source/moorthy.md @@ -0,0 +1,36 @@ +--- +title: Moorthy +category: Developer > Rensselaer Center for Open Source (RCOS) +redirect_from: + - /developer/rcos_moorthy + - /developer/rpi_summer_rcos + - /developer/rpi_summer_rcos/index +--- + + +[Professor Mukkai Krishnamoorthy](https://www.cs.rpi.edu/~moorthy/), +affectionately known as Moorthy, is the heart and soul of the +[Rensselaer Center for Open Source (RCOS)](https://rcos.io/), of which +he served as director from 2007-2018. With Moorthy's support and +encouragement, membership in RCOS grew from a couple dozen students +per year to well over 100 students per term -- and somehow he still +knew everyone's name and technology for each project! Moorthy +emphasizes students' freedom to explore and learn and create. + +Thus, in honor of our beloved faculty member, Professor +Krishnamoorthy, we name the Submitty [duck](https://en.wikipedia.org/wiki/Rubber_duck_debugging) mascot "Moorthy". + +![x](/images/moorthy_duck.png){:width="200px"} + +See also: + +* [The Beginnings of the Rensselaer Center for Open Source, by Severin Ibarluzea](https://medium.com/@seveibar/the-beginnings-of-the-rensselaer-center-for-open-source-7c8fe7613b7d) + +* [Moorthy juggling and reciting digits of Pi](https://www.youtube.com/watch?v=TAFTmQfYNRI) + + + + + + + diff --git a/_docs/developer/software_and_system_design/coding_style_guide/c++.md b/_docs/developer/software_and_system_design/coding_style_guide/c++.md new file mode 100644 index 00000000..986a5b66 --- /dev/null +++ b/_docs/developer/software_and_system_design/coding_style_guide/c++.md @@ -0,0 +1,45 @@ +--- +title: C++ +category: Developer > Software and System Design > Coding Style Guide +redirect_from: + - /developer/coding_style_guide/c++ +--- + +To do this we've modified certain important aspects of the [Google Style Guide](https://google.github.io/styleguide/cppguide.html). This is a living document and will likely change as new issues arise. + +When contributing to the homework server keep the following guidelines in mind. + +### General Rules + +* Code should never be more than 80 characters per line + +### Header Files + +* Header files should have #define guards +* Only fully define a function in the class prototype if the code for the function is one line. +* C++ code can be written below the class prototype in the header file + +### Commenting + +* Declaration comments describe use of the function; comments at the definition of a function describe its operation. +* Non-function/non-class comments that describe some functionality of a block of code should be less than 60 characters + +### Naming + +#### Class Names + +Type or class names should begin with a capital letter and have every word after begin with a capital letter (camel casing). + +```class MyClassName {...}``` + +#### Function Names + +All functions should be camel cased with the first letter being lowercase. + +```void getJesseSushi();``` + +#### Variable Names + +All variables should be lower case with underscores + +```int cats_in_house = 0;``` diff --git a/_docs/developer/software_and_system_design/coding_style_guide/css.md b/_docs/developer/software_and_system_design/coding_style_guide/css.md new file mode 100644 index 00000000..d64ee9d4 --- /dev/null +++ b/_docs/developer/software_and_system_design/coding_style_guide/css.md @@ -0,0 +1,128 @@ +--- +title: CSS +category: Developer +category: Developer > Software and System Design > Coding Style Guide +redirect_from: + - /developer/coding_style_guide/css +--- + +## Styling + +Classes vs IDs: +* Classes are for repeated elements - make these as general as possible +* IDs *must* only have one associated element at any given time - this is for specifying your module + +Both CSS classes and IDs should be written as dash-separated-variables. +Example HTML: +``` +

Title

+

Text.

+``` + +When writing CSS, Submitty uses the following guidelines: +* Use 4 space indents +* Use K&R style braces (one brace on the same line on the selector) +* For selectors which specify elements with a comma, write each element on a separate line +* Group all @media queries at the bottom, under as few breakpoints as possible + +Example CSS: +``` +#my-header, +.my-class { + display: none; +} + +@media (min-width: 541px) { + #my-header { + display: absolute; + } + + .my-class { + display: block; + } +} +``` + +_NOTE: We will be implementing a minifier so there is no need to do things like remove the whitespace +after a colon, but there is nothing wrong with using shorthand properties._ + +If possible, separate classes for specific cases and general use. For example, `global.css`'s +`.system-message` class specifies the positioning / sizing of a message: +``` +.system-message { + width: 100%; + text-align: center; + margin: auto; + font-size: 1.5em; + font-weight: bold; +} +``` +On the other hand `server.css`'s `.warning` and `.danger` classes keep a consistent color for other elements to use: +``` +.warning { + background: #fff3cd; + color: #856404; +} + +.danger { + background: #f2dede; + color: #b94a48; +} +``` + +Combining these, both our noscript error and our system message notifications are displayed with a consistent +image - with respect to each other and other warning/danger messages on the site. When choosing a color for +your element, check to see what other colors are used in similar situations and choose from something that +already exists. + +## Responsive Design + +Responsive design is the technique of displaying a page differently to fit different devices. This can +mostly be done through CSS @media queries. These queries add additional CSS when specific conditions +about the user's device is met. We implement a "mobile first design" that does not use @media queries for +mobile devices but instead uses @media queries for additional rules on tablet / desktop devices. + +Generally, our CSS is structured like this: +``` +.my-class { + /* General CSS as well as special rules for small (mobile) devices */ +} + +@media (min-width: 541px) { + .my-class { + /* Additional special CSS for medium (tablet) and large (desktop) devices */ + } +} + +@media (min-width: 768px) { + .my-class { + /* Additional special CSS for large (desktop) devices only */ + } +} +``` + +It might not always be necessary to use @media queries; some things render just fine on all devices. +When choosing your breakpoints (the pixel cutoffs), slowly decrease your screen size to find at which +widths your UI loses quality. If you are having trouble determining specific breakpoints for your module, +the ones provided in the example above should cover most cases. + +## File Architecture: + +Each `.twig` file should generally have a paired `.css` file. Do not use inline CSS or `