From 0c402a61ca212ce817d54f7c9f287036dffaafdf Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Mon, 28 Oct 2024 03:36:25 +0000 Subject: [PATCH 01/27] enhance: update README.md and split into several related files --- README.md | 266 +----------------- .../insert-config-database.md | 16 ++ .../insert-rubric-database.md | 25 ++ .../update-rubric-database.md | 40 +++ getting-started/getting-started.md | 135 +++++++++ getting-started/linux.md | 1 + getting-started/macos.md | 1 + getting-started/windows.md | 60 ++++ 8 files changed, 290 insertions(+), 254 deletions(-) create mode 100644 getting-started/db-insert-statements/insert-config-database.md create mode 100644 getting-started/db-insert-statements/insert-rubric-database.md create mode 100644 getting-started/db-insert-statements/update-rubric-database.md create mode 100644 getting-started/getting-started.md create mode 100644 getting-started/linux.md create mode 100644 getting-started/macos.md create mode 100644 getting-started/windows.md diff --git a/README.md b/README.md index cefe1edbd..5b7bfeb5e 100644 --- a/README.md +++ b/README.md @@ -46,262 +46,20 @@ property `db.url` is set to `db:3306` ## Development -### Pre-requisites +First read the relevant OS-specific instructions: -##### Dev Container (recommended for Windows) +- [Windows](getting-started/windows.md) +- [Linux](getting-started/linux.md) +- [MacOS](getting-started/macos.md) -You can run all of IntelliJ inside a docker container, which would allow debugging the code on Windows -machines. This requires having docker installed and running on your machine. -To do this, navigate to `.devcontainer/devcontainer.json` in IntelliJ. There should be an icon that pops up next to -the opening curly brace. Click the icon, then select `Create Dev Container and Clone Sources...`. This should pop up -a dialog box that allows you to change a few options about the container. Look through them and change what you need, -then hit the `Build Container and Continue` button. Wait for IntelliJ and Docker to build everything. You may need to -click a few buttons along the way. Eventually a new IntelliJ window will pop up from the dev container. Follow the -[Yarn](#nodeyarn) instructions and [Getting Started](#getting-started) steps below with the new window. -Use `host.docker.internal` as your db-host argument. +Then follow the [Getting Started](getting-started/getting-started.md) page to Get Started! -To reopen the container after you've closed it, navigate to the `.devcontainer/devcontainer.json` file again, -click the icon, and select `Show Dev Containers`. Select the container and it should reopen the second IntelliJ. -If nothing appears, make sure the docker engine is running (perhaps by opening Docker Desktop). +### How to Contribute -##### Other Notes for Windows Development +Here are a few tips for first projects or tasks to learn the autograder: +- Review the Sequence/Class Diagrams (_coming soon_) and try creating one +- Add documentation +- Find a section of under-tested code and add some unit tests +- Take a look through the GitHub repo's Issues page and find one you like, especially ones labeled "good first issue" -The autograder unfortunately won't work directly from Windows, so you must use Docker or WSL for your database. - -If you run the autograder from WSL, you can use your normal Windows MySQL for the database. (Or you can install MySQL -for Linux from within WSL, but having both Windows and Linux MySQL servers can cause weird issues.) You can't simply -use `localhost` as the database hostname, however, since that refers to the WSL instance. Running `echo $(hostname)` -from a WSL terminal will tell you what your computer's host name is (ex. `LAPTOP-ABC123`). Appending `.local` to that ( -ex. `LAPTOP-ABC123.local`) gives you the hostname that WSL uses to refer to the Windows machine. Use this as -the `--db-host` program argument. - -By default, MySQL users have "Limit to Host Matching" set to `localhost`, which does not allow requests coming from the -WSL virtual machine. In MySQL Workbench, you will have to expand this. The easiest way is to change it to `%`, which allows all hostnames (but it is -highly recommended that you do only do this for a new user with restricted privileges rather than using root). Another option is to -use `wsl hostname -I` to determine the WSL instance's IP address and use that, but this IP may change whenever WSL restarts. - -#### Node/Yarn - -The frontend is built using Vue.js. To run the frontend, you will need to have `yarn`. -After installing `Node`, run the following to enable `yarn` globally: - -```bash -corepack enable -``` - -note: `sudo` may be required - -(see [installing `yarn`](https://yarnpkg.com/getting-started/install)) - -#### Backend - -The backend of the app can be run with either `maven`, or by running your own MySQL server. - -##### Maven - -Go fish🐟 These instructions are not included in this file. - -#### Database - -You can run the database inside a Docker container, or locally with your own MySQL server. - -##### Docker MySQL Server - -Run the following in the root of the project to start the db container: - -```bash -docker compose up db -d -``` - -##### Manual MySQL Server - -Go fish🐟 These instructions are not included in this file. - -### Getting Started - -NOTE: These instructions will help you set up this project in IntelliJ. -If there are any holes or gaps in the instructions, please submit a new pull request -to preserve the learned knowledge for future generations. - -1. Clone the repo onto your local machine. -2. Ensure that you are using the latest version of JVM. The system currently requires version 21+. -3. Use `yarn` to install all dependencies. This must be done from the _front end_ root folder. (If using WSL, run this - from an actual WSL terminal. Windows-based shells, even POSIX ones, won't install the correct files.) - ```bash - cd src/main/resources/frontend - yarn - ``` -4. Setup "Server" _Run Configuration_ - - Navigate to the server file: `src/main/java/edu/byu/cs/server/Server.java` - - Click the "Run" button to run `Server.main()` - - This will give you a _Run Configuration_ that you can modify in the following steps. -5. Set up [program arguments](#program-arguments) - - Reference the [subtitle below](#program-arguments) for the list of required arguments - - Prepare the values you will use for each argument - - Put them all onto a single line, with each argument name followed by its value - - Ex. `--arg-1 arg1Val --arg-2 arg2Val` - - Edit the "Server" run configuration - - Paste in the single line of parameters to the line titled "Program arguments" - - Save & apply the changes -6. **Run the Autograder Locally** - - Run your "Server" run configuration - - Run the frontend by referencing the code below. In the case you are running on the - Autograder inside a dev container, you may need to add the `--host` option at the - end of the `yarn dev` command (`yarn dev --host`). - ```bash - cd src/main/resources/frontend - yarn dev - ``` - - Load the configuration related tables by referencing the [section below](#loading-the-configuration-related-tables) - -#### Program Arguments - -For both deployment and development, the following program arguments are required to be set. Some typical -values for development are provided; notice that the URLs all reference localhost, but the port numbers have -been filled in with default values. Update these as needed to match your environment. - -``` ---db-user ---db-pass ---db-host localhost ---db-port 3306 ---db-name autograder ---frontend-url http://localhost:5173 ---cas-callback-url http://localhost:8080/auth/callback ---canvas-token -``` - -While you can use any root user credentials to access the MySQL database, you may be interested in creating -a special login for this project with restricted privileges (DELETE and CREATE USER administrator privileges are -required). That decision is left to you. - -A Canvas Authorization Key is required to run the project. The Autograder currently relies on information from Canvas -to give you admin access to the app (see [#164](https://github.com/softwareconstruction240/autograder/issues/164)). -To generate a Canvas API key: - -1. Login to [Canvas](https://byu.instructure.com/) -2. Visit your [Profile Settings](https://byu.instructure.com/profile/settings) - - Navigate here manually as "Account > Settings" -3. Scroll down to the **Approved Integrations** section -4. Click "+ New Access Token" -5. Provide the requested information in the modal box -6. Copy the generated access token -7. Use it as the value of the `--canvas-token` program argument above - -#### Loading the Configuration Related Tables - -As of right now, you will need to manually insert the correct values into the `rubric_config` table before being -able to run the actual autograding on the autograder. Down below is an `INSERT` statement to do that. - -UPDATED AS OF 'SUMMER 2024'. Note that the primary thing that needs to be updated here is the `rubric_id` column. -```mysql -INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) VALUES -('GitHub', 'GITHUB_REPO', 'GitHub Repository', 'Two Git commits: one for creating the repository and another for `notes.md`.', 15, '_6829'), -('Phase0', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_649'), -('Phase0', 'PASSOFF_TESTS', 'Functionality', 'All pass off test cases succeed', 125, '_1958'), -('Phase1', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_7800'), -('Phase1', 'PASSOFF_TESTS', 'Functionality', 'All pass off test cases succeed', 125, '_1958'), -('Phase3', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90344_2520'), -('Phase3', 'PASSOFF_TESTS', 'Web API Works', 'All pass off test cases in StandardAPITests.java succeed', 125, '_5202'), -('Phase3', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '_3003'), -('Phase3', 'UNIT_TESTS', 'Unit Tests', 'All test cases pass\nEach public method on your Service classes has two test cases, one positive test and one negative test\nEvery test case includes an Assert statement of some type', 25, '90344_776'), -('Phase4', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90346_6245'), -('Phase4', 'PASSOFF_TESTS', 'Functionality', 'All pass off test cases succeed', 100, '_2614'), -('Phase4', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '90346_8398'), -('Phase4', 'UNIT_TESTS', 'Unit Tests', 'All test cases pass\nEach public method on DAO classes has two test cases, one positive test and one negative test\nEvery test case includes an Assert statement of some type', 25, '90346_5755'), -('Phase5', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90347_8497'), -('Phase5', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '90347_9378'), -('Phase5', 'UNIT_TESTS', 'Unit Tests', 'All test cases pass\nEach public method on the Server Facade class has two test cases, one positive test and one negative test\nEvery test case includes an Assert statement of some type', 25, '90347_2215'), -('Phase6', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90348_9048'), -('Phase6', 'PASSOFF_TESTS', 'Automated Pass Off Test Cases', 'Each provided test case passed is worth a proportional number of points ((passed / total) * 50).', 50, '90348_899'), -('Phase6', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '90348_3792'), -('Quality', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, NULL); -``` - -Now you need to get the correct Canvas course ID. Go to Canvas and select the current CS 240 course. The URL should -change to something like `https://byu.instructure.com/courses/` where `` is the number -you need to use inside the `configuration` table. You can set this by logging into the autograder and using the -`Update Manually` button in the `Config` tab. Click that button and modify the `Course Number` input and then -click `Submit`. - -As of 'SUMMER 2024', the course number is `26822`. - -To ensure that the assignment IDs and rubric IDs/points are synced with Canvas, go -to the `config` tab, select the button `Update using Canvas`, and select `Yes`. If there's a slight -issue, you may need to explore updating the course IDs manually, whether that be directly though the database or by -clicking the `Update Manually` in the `config` tab. - ---- - -Additionally, if you want (not required), you can insert values into the `configuration` table manually -(although the step above should do it automatically). - -UPDATED AS OF 'SUMMER 2024'. Note that the primary thing that needs to be updated is the value of the `COURSE_NUMBER` -and each of the assignment numbers. - -```mysql -INSERT INTO configuration (config_key, value) VALUES -('BANNER_MESSAGE', ''), -('GITHUB_ASSIGNMENT_NUMBER', 941080), -('PHASE0_ASSIGNMENT_NUMBER', 941084), -('PHASE1_ASSIGNMENT_NUMBER', 941085), -('PHASE3_ASSIGNMENT_NUMBER', 941087), -('PHASE4_ASSIGNMENT_NUMBER', 941088), -('PHASE5_ASSIGNMENT_NUMBER', 941089), -('PHASE6_ASSIGNMENT_NUMBER', 941090), -('COURSE_NUMBER', 26822), -('STUDENT_SUBMISSIONS_ENABLED', '[Phase0, Phase1, Phase3, Phase4, Phase5, Phase6, Quality, GitHub]'); -``` - -#### Environment Variables - -If you are running Loki locally (not required), then you must set the following environment variable: -``` -LOKI_URL= -``` - -The value can be either `localhost:3100` (if you are NOT using docker to develop the app) or `loki:3100` -(if you are using docker to develop the app). - -##### Updating from the Old Rubric Config Table. - -If you have the autograder prior to 'SUMMER 2024', the following SQL should do the job of updating -the `rubric_config` table: - -UPDATED AS OF 'SUMMER 2024' -```mysql -ALTER TABLE rubric_config ADD rubric_id VARCHAR(15); --- could be ten as no rubric ids so far are longer than 10, but just in case --- we need extra space. It's up to you if you want to change it. I don't mind. -UPDATE rubric_config SET rubric_id = '_6829' WHERE phase = 'GitHub'; - -UPDATE rubric_config SET rubric_id = '_1958' WHERE phase = 'Phase0' AND type = 'PASSOFF_TESTS'; -INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) - VALUES ('Phase0', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_649'); - -UPDATE rubric_config SET rubric_id = '_1958' WHERE phase = 'Phase1'; -INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) - VALUES ('Phase1', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_7800'); - -UPDATE rubric_config SET rubric_id = '_5202' WHERE phase = 'Phase3' and type = 'PASSOFF_TESTS'; -UPDATE rubric_config SET rubric_id = '90344_776' WHERE phase = 'Phase3' and type = 'UNIT_TESTS'; -UPDATE rubric_config SET rubric_id = '_3003' WHERE phase = 'Phase3' and type = 'QUALITY'; -INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) - VALUES ('Phase3', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90344_2520'); - -UPDATE rubric_config SET rubric_id = '_2614' WHERE phase = 'Phase4' and type = 'PASSOFF_TESTS'; -UPDATE rubric_config SET rubric_id = '90346_5755' WHERE phase = 'Phase4' and type = 'UNIT_TESTS'; -UPDATE rubric_config SET rubric_id = '90346_8398' WHERE phase = 'Phase4' and type = 'QUALITY'; -INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) - VALUES ('Phase4', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90346_6245'); - -UPDATE rubric_config SET rubric_id = '90347_2215' WHERE phase = 'Phase5' and type = 'UNIT_TESTS'; -UPDATE rubric_config SET rubric_id = '90347_9378' WHERE phase = 'Phase5' and type = 'QUALITY'; -INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) - VALUES ('Phase5', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90347_8497'); - -UPDATE rubric_config SET rubric_id = '90348_899' WHERE phase = 'Phase6' and type = 'PASSOFF_TESTS'; -UPDATE rubric_config SET rubric_id = '90348_3792' WHERE phase = 'Phase6' and type = 'QUALITY'; -INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) - VALUES ('Phase6', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90348_9048'); -``` \ No newline at end of file +Don't be afraid to submit a PR, and most importantly, just get stuck in! \ No newline at end of file diff --git a/getting-started/db-insert-statements/insert-config-database.md b/getting-started/db-insert-statements/insert-config-database.md new file mode 100644 index 000000000..d48906904 --- /dev/null +++ b/getting-started/db-insert-statements/insert-config-database.md @@ -0,0 +1,16 @@ +UPDATED AS OF 'SUMMER 2024'. Note that the primary thing that needs to be updated is the value of the `COURSE_NUMBER` +and each of the assignment numbers. + +```mysql +INSERT INTO configuration (config_key, value) VALUES +('BANNER_MESSAGE', ''), +('GITHUB_ASSIGNMENT_NUMBER', 941080), +('PHASE0_ASSIGNMENT_NUMBER', 941084), +('PHASE1_ASSIGNMENT_NUMBER', 941085), +('PHASE3_ASSIGNMENT_NUMBER', 941087), +('PHASE4_ASSIGNMENT_NUMBER', 941088), +('PHASE5_ASSIGNMENT_NUMBER', 941089), +('PHASE6_ASSIGNMENT_NUMBER', 941090), +('COURSE_NUMBER', 26822), +('STUDENT_SUBMISSIONS_ENABLED', '[Phase0, Phase1, Phase3, Phase4, Phase5, Phase6, Quality, GitHub]'); +``` diff --git a/getting-started/db-insert-statements/insert-rubric-database.md b/getting-started/db-insert-statements/insert-rubric-database.md new file mode 100644 index 000000000..5057aa45b --- /dev/null +++ b/getting-started/db-insert-statements/insert-rubric-database.md @@ -0,0 +1,25 @@ +UPDATED AS OF 'SUMMER 2024'. Note that the primary thing that needs to be updated here is the `rubric_id` column. + +```mysql +INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) VALUES +('GitHub', 'GITHUB_REPO', 'GitHub Repository', 'Two Git commits: one for creating the repository and another for `notes.md`.', 15, '_6829'), +('Phase0', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_649'), +('Phase0', 'PASSOFF_TESTS', 'Functionality', 'All pass off test cases succeed', 125, '_1958'), +('Phase1', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_7800'), +('Phase1', 'PASSOFF_TESTS', 'Functionality', 'All pass off test cases succeed', 125, '_1958'), +('Phase3', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90344_2520'), +('Phase3', 'PASSOFF_TESTS', 'Web API Works', 'All pass off test cases in StandardAPITests.java succeed', 125, '_5202'), +('Phase3', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '_3003'), +('Phase3', 'UNIT_TESTS', 'Unit Tests', 'All test cases pass\nEach public method on your Service classes has two test cases, one positive test and one negative test\nEvery test case includes an Assert statement of some type', 25, '90344_776'), +('Phase4', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90346_6245'), +('Phase4', 'PASSOFF_TESTS', 'Functionality', 'All pass off test cases succeed', 100, '_2614'), +('Phase4', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '90346_8398'), +('Phase4', 'UNIT_TESTS', 'Unit Tests', 'All test cases pass\nEach public method on DAO classes has two test cases, one positive test and one negative test\nEvery test case includes an Assert statement of some type', 25, '90346_5755'), +('Phase5', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90347_8497'), +('Phase5', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '90347_9378'), +('Phase5', 'UNIT_TESTS', 'Unit Tests', 'All test cases pass\nEach public method on the Server Facade class has two test cases, one positive test and one negative test\nEvery test case includes an Assert statement of some type', 25, '90347_2215'), +('Phase6', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90348_9048'), +('Phase6', 'PASSOFF_TESTS', 'Automated Pass Off Test Cases', 'Each provided test case passed is worth a proportional number of points ((passed / total) * 50).', 50, '90348_899'), +('Phase6', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, '90348_3792'), +('Quality', 'QUALITY', 'Code Quality', 'Chess Code Quality Rubric (see GitHub)', 30, NULL); +``` diff --git a/getting-started/db-insert-statements/update-rubric-database.md b/getting-started/db-insert-statements/update-rubric-database.md new file mode 100644 index 000000000..133df80d1 --- /dev/null +++ b/getting-started/db-insert-statements/update-rubric-database.md @@ -0,0 +1,40 @@ +If you have the autograder prior to 'SUMMER 2024', the following SQL should do the job of updating +the `rubric_config` table: + +UPDATED AS OF 'SUMMER 2024' +```mysql +ALTER TABLE rubric_config ADD rubric_id VARCHAR(15); +-- could be ten as no rubric ids so far are longer than 10, but just in case +-- we need extra space. It's up to you if you want to change it. I don't mind. +UPDATE rubric_config SET rubric_id = '_6829' WHERE phase = 'GitHub'; + +UPDATE rubric_config SET rubric_id = '_1958' WHERE phase = 'Phase0' AND type = 'PASSOFF_TESTS'; +INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) +VALUES ('Phase0', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_649'); + +UPDATE rubric_config SET rubric_id = '_1958' WHERE phase = 'Phase1'; +INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) +VALUES ('Phase1', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90342_7800'); + +UPDATE rubric_config SET rubric_id = '_5202' WHERE phase = 'Phase3' and type = 'PASSOFF_TESTS'; +UPDATE rubric_config SET rubric_id = '90344_776' WHERE phase = 'Phase3' and type = 'UNIT_TESTS'; +UPDATE rubric_config SET rubric_id = '_3003' WHERE phase = 'Phase3' and type = 'QUALITY'; +INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) +VALUES ('Phase3', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90344_2520'); + +UPDATE rubric_config SET rubric_id = '_2614' WHERE phase = 'Phase4' and type = 'PASSOFF_TESTS'; +UPDATE rubric_config SET rubric_id = '90346_5755' WHERE phase = 'Phase4' and type = 'UNIT_TESTS'; +UPDATE rubric_config SET rubric_id = '90346_8398' WHERE phase = 'Phase4' and type = 'QUALITY'; +INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) +VALUES ('Phase4', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90346_6245'); + +UPDATE rubric_config SET rubric_id = '90347_2215' WHERE phase = 'Phase5' and type = 'UNIT_TESTS'; +UPDATE rubric_config SET rubric_id = '90347_9378' WHERE phase = 'Phase5' and type = 'QUALITY'; +INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) +VALUES ('Phase5', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90347_8497'); + +UPDATE rubric_config SET rubric_id = '90348_899' WHERE phase = 'Phase6' and type = 'PASSOFF_TESTS'; +UPDATE rubric_config SET rubric_id = '90348_3792' WHERE phase = 'Phase6' and type = 'QUALITY'; +INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) +VALUES ('Phase6', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90348_9048'); +``` \ No newline at end of file diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md new file mode 100644 index 000000000..4056f26ec --- /dev/null +++ b/getting-started/getting-started.md @@ -0,0 +1,135 @@ +# Getting Started + +### Pre-requisites + +Operating System-specific instructions (read the applicable doc before continuing): + +- [Windows](windows.md) +- [Linux](linux.md) +- [MacOS](macos.md) + +#### Node/Yarn + +The frontend is built using Vue.js. To run the frontend, you will need to have `yarn` (see +[installing yarn](https://yarnpkg.com/getting-started/install)). +After installing `Node` if necessary, run the following to enable `yarn` globally (sudo may be required): + +```bash +corepack enable +``` + +#### Backend Database + +You can run the database either locally with your own MySQL server or inside a Docker container. To run the database +inside its own Docker container, run the following in the root of the project: + +```bash +docker compose up db -d +``` + +## Getting Started + +NOTE: These instructions will help you set up this project in IntelliJ. +If there are any holes or gaps in the instructions, please submit a new pull request +to preserve the learned knowledge for future generations. + +1. Clone the repo onto your local machine. +2. Ensure that you are using the latest version of JVM. The system currently requires version 21+. +3. Use `yarn` to install all dependencies. This must be done from the _front end_ root folder. (If using WSL, run this + from an actual WSL terminal. Windows-based shells, even POSIX ones, won't install the correct files.) + ```bash + cd src/main/resources/frontend + yarn + ``` +4. Setup "Server" _Run Configuration_ + - Navigate to the server file: `src/main/java/edu/byu/cs/server/Server.java` + - Click the "Run" button to run `Server.main()` + - This will give you a _Run Configuration_ that you can modify in the following steps. +5. Set up [program arguments](#program-arguments) + - Reference the [subtitle below](#program-arguments) for the list of required arguments + - Prepare the values you will use for each argument + - Put them all onto a single line, with each argument name followed by its value + - Ex. `--arg-1 arg1Val --arg-2 arg2Val` + - Edit the "Server" run configuration + - Paste in the single line of parameters to the line titled "Program arguments" + - Save & apply the changes +6. **Run the Autograder Locally** + - Run your "Server" run configuration + - Run the frontend by referencing the code below. In the case you are running on the + Autograder inside a dev container, you may need to add the `--host` option at the + end of the `yarn dev` command (`yarn dev --host`). + ```bash + cd src/main/resources/frontend + yarn dev + ``` + - Load the configuration related tables by referencing the [section below](#loading-the-configuration-related-tables) + +#### Program Arguments + +For both deployment and development, the following program arguments are required to be set. Some typical +values for development are provided; notice that the URLs all reference localhost, but the port numbers have +been filled in with default values. Update these as needed to match your environment. + +``` +--db-user +--db-pass +--db-host localhost +--db-port 3306 +--db-name autograder +--frontend-url http://localhost:5173 +--cas-callback-url http://localhost:8080/auth/callback +--canvas-token +``` + +While you can use any root user credentials to access the MySQL database, you may be interested in creating +a special login for this project with restricted privileges (DELETE and CREATE USER administrator privileges are +required). That decision is left to you. + +##### Canvas Integration + +A Canvas Authorization Key is required to link the project to Canvas. If you don't need Canvas integration, +`--canvas-token ` can be replaced with `--use-canvas false`, which mocks Canvas calls. Then you can +skip this section. + +To generate a Canvas API key: + +1. Login to [Canvas](https://byu.instructure.com/) +2. Visit your [Profile Settings](https://byu.instructure.com/profile/settings) + - Navigate here manually as "Account > Settings" +3. Scroll down to the **Approved Integrations** section +4. Click "+ New Access Token" +5. Provide the requested information in the modal box +6. Copy the generated access token +7. Use it as the value of the `--canvas-token` program argument above + +To get the correct Canvas course ID, go to Canvas and select the current CS 240 course. The URL should +change to something like `https://byu.instructure.com/courses/` where `` is the number +you need to use inside the `configuration` table. You can set this by logging into the autograder and using the +`Update Manually` button in the `Config` tab. Click that button and modify the `Course Number` input and then +click `Submit`. + +As of 'SUMMER 2024', the course number is `26822`. + +To ensure that the assignment IDs and rubric IDs/points are synced with Canvas, go +to the `config` tab, select the button `Update using Canvas`, and select `Yes`. If there's a slight +issue, you may need to explore updating the course IDs manually, whether that be directly though the database or by +clicking the `Update Manually` in the `config` tab. + +Additionally, if you want (not required), you can insert values into the `configuration` table manually +(although the step above should do it automatically). [Here](db-insert-statements/insert-config-database.md) is the insert statement. + +#### Environment Variables + +If you are running Loki locally (not required), then you must set the `LOKI_URL` environment variable. The value can be +either `localhost:3100` (if you are NOT using docker to develop the app) or `loki:3100` (if you are using docker to +develop the app). + +#### Loading the Configuration Related Tables + +As of right now, you will need to manually insert the correct values into the `rubric_config` table before being +able to run the actual grading on the autograder. [Here](db-insert-statements/insert-rubric-database.md) is an insert statement for that. + +##### Updating from the Old Rubric Config Table. + +If you have the autograder prior to 'SUMMER 2024', [this SQL statement](db-insert-statements/update-rubric-database.md) should do the job of updating +the `rubric_config` table. diff --git a/getting-started/linux.md b/getting-started/linux.md new file mode 100644 index 000000000..71dfaa10e --- /dev/null +++ b/getting-started/linux.md @@ -0,0 +1 @@ +Nothing here currently. \ No newline at end of file diff --git a/getting-started/macos.md b/getting-started/macos.md new file mode 100644 index 000000000..71dfaa10e --- /dev/null +++ b/getting-started/macos.md @@ -0,0 +1 @@ +Nothing here currently. \ No newline at end of file diff --git a/getting-started/windows.md b/getting-started/windows.md new file mode 100644 index 000000000..787e847fd --- /dev/null +++ b/getting-started/windows.md @@ -0,0 +1,60 @@ +# Windows + +The autograder unfortunately won't work directly from Windows, so it must be run inside a Docker container +(recommended) or inside WSL (possible but can be finicky). When running the autograder inside a Docker container, +you will need to use a _Dev Container_ if you want to use IntelliJ's or VSCode's debugging tools. + +Either way, running your MySQL server locally on your Windows machine should work for the database. + +### Development inside a Dev Container (recommended) + +The easiest way to debug a program running inside a Docker container is via a dev container. This essentially allows +you to run all of IntelliJ (or VSCode) inside the container, which enables debugging the code on Windows machines. + +This requires having Docker installed and running on your machine. To develop with IntelliJ, it also requires the full +professional version (or a student license of it). The VSCode equivalent is free. + +###### IntelliJ + +To do this in IntelliJ, navigate to `.devcontainer/devcontainer.json`. There should be an icon that pops up next to +the opening curly brace. Click the icon, then select `Create Dev Container and Clone Sources...`. (Not to be confused +with `Mount Sources`, which doesn't quite work. If the Clone Sources option does not appear, see below.) This should +pop up a dialog box that allows you to change a few options about the container. Look through them +and change what you need, then hit the `Build Container and Continue` button. Wait for IntelliJ and Docker to build +everything. You may need to click a few buttons along the way. Eventually a new IntelliJ window will pop up from the +dev container. Follow the [Getting Started](getting-started.md) steps with the new window. +Use `host.docker.internal` as your db-host argument; this tells docker to look for the database on your local Windows +machine rather than inside the container. To reopen the container after you've closed it, navigate to the +`.devcontainer/devcontainer.json` file again, click the icon, and select `Show Dev Containers`. Select the container +and it should reopen the second IntelliJ. If nothing appears, make sure the docker engine is running +(perhaps by opening Docker Desktop). + +If you don't see an option to `Clone Sources`, you can do the same thing via JetBrains Gateway. Download and install +it if you haven't already. (Installing via JetBrains Toolbox is probably the easiest way.) Open Gateway, select +`Dev Containers`, and click `New Dev Container`. Choose `From VCS Project`, select Intellij IDEA from the dropdown, +and paste a link to the autograder GitHub repo (or your fork of it). The remainder of the setup after clicking +`Build Container and Continue` is the same as above, except that to reopen the container after you've closed it, you'll +need to open Gateway again and select the dev container from there. + +###### VSCode + +Go fish🐟 These instructions are not included in this file. It should be possible to simply use VSCode's Dev Containers +extension, though. + +### Development inside WSL + +If Docker doesn't work for some reason, you can use WSL. You'll be able to simply clone and run the autograder, except +that everything in these instructions should be done via a WSL terminal _and_ inside a WSL directory. If you use a +Windows directory, like Desktop/chess, you might run into file permissions errors. "Unix-like" shells, such as Git +Bash, will not work: it needs to be a true WSL terminal. + +For the `--db-host` program argument, you can't simply use `localhost` (assuming your database is running on Windows), +since that will refer to the WSL instance. Running `echo $(hostname)` from a WSL terminal will tell you what your +computer's true hostname is (ex. `LAPTOP-ABC123`). Appending `.local` to that (ex. `LAPTOP-ABC123.local`) gives you +the hostname that WSL uses to refer to the Windows machine. Use this as the `--db-host` program argument. + +By default, MySQL users have "Limit to Host Matching" set to `localhost`, which does not allow requests coming from the +WSL virtual machine. You will have to expand this in MySQLWorkbench (under Server, click "Users and Privileges"). The +easiest way is to change it to `%`, which allows all hostnames (but it is highly recommended that you only do this for a +new user with restricted privileges, rather than using root). Another option is to run `wsl hostname -I` in PowerShell +to determine the WSL instance's IP address, then simply hardcode that, but this IP may change when WSL restarts. \ No newline at end of file From c5d499a5b9c8e69833dbe7e95a362a4dd7568575 Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Mon, 28 Oct 2024 19:33:46 +0000 Subject: [PATCH 02/27] fix: use consistent header sizing --- getting-started/getting-started.md | 23 +++++++++++++++-------- getting-started/windows.md | 8 ++++---- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index 4056f26ec..ba07dad1b 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -### Pre-requisites +## Pre-requisites Operating System-specific instructions (read the applicable doc before continuing): @@ -8,7 +8,7 @@ Operating System-specific instructions (read the applicable doc before continuin - [Linux](linux.md) - [MacOS](macos.md) -#### Node/Yarn +### Node/Yarn The frontend is built using Vue.js. To run the frontend, you will need to have `yarn` (see [installing yarn](https://yarnpkg.com/getting-started/install)). @@ -18,7 +18,7 @@ After installing `Node` if necessary, run the following to enable `yarn` globall corepack enable ``` -#### Backend Database +### Backend Database You can run the database either locally with your own MySQL server or inside a Docker container. To run the database inside its own Docker container, run the following in the root of the project: @@ -64,7 +64,7 @@ to preserve the learned knowledge for future generations. ``` - Load the configuration related tables by referencing the [section below](#loading-the-configuration-related-tables) -#### Program Arguments +### Program Arguments For both deployment and development, the following program arguments are required to be set. Some typical values for development are provided; notice that the URLs all reference localhost, but the port numbers have @@ -85,7 +85,12 @@ While you can use any root user credentials to access the MySQL database, you ma a special login for this project with restricted privileges (DELETE and CREATE USER administrator privileges are required). That decision is left to you. -##### Canvas Integration +### Canvas Integration + +To link the autograder with Canvas, you will need to generate a Canvas API key and set the autograder to the current +Course and Assignment ID numbers on Canvas. + +#### Canvas API Key A Canvas Authorization Key is required to link the project to Canvas. If you don't need Canvas integration, `--canvas-token ` can be replaced with `--use-canvas false`, which mocks Canvas calls. Then you can @@ -102,6 +107,8 @@ To generate a Canvas API key: 6. Copy the generated access token 7. Use it as the value of the `--canvas-token` program argument above +#### Canvas Data + To get the correct Canvas course ID, go to Canvas and select the current CS 240 course. The URL should change to something like `https://byu.instructure.com/courses/` where `` is the number you need to use inside the `configuration` table. You can set this by logging into the autograder and using the @@ -118,18 +125,18 @@ clicking the `Update Manually` in the `config` tab. Additionally, if you want (not required), you can insert values into the `configuration` table manually (although the step above should do it automatically). [Here](db-insert-statements/insert-config-database.md) is the insert statement. -#### Environment Variables +### Environment Variables If you are running Loki locally (not required), then you must set the `LOKI_URL` environment variable. The value can be either `localhost:3100` (if you are NOT using docker to develop the app) or `loki:3100` (if you are using docker to develop the app). -#### Loading the Configuration Related Tables +### Loading the Configuration Related Tables As of right now, you will need to manually insert the correct values into the `rubric_config` table before being able to run the actual grading on the autograder. [Here](db-insert-statements/insert-rubric-database.md) is an insert statement for that. -##### Updating from the Old Rubric Config Table. +#### Updating from the Old Rubric Config Table If you have the autograder prior to 'SUMMER 2024', [this SQL statement](db-insert-statements/update-rubric-database.md) should do the job of updating the `rubric_config` table. diff --git a/getting-started/windows.md b/getting-started/windows.md index 787e847fd..14ea18dd2 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -6,7 +6,7 @@ you will need to use a _Dev Container_ if you want to use IntelliJ's or VSCode's Either way, running your MySQL server locally on your Windows machine should work for the database. -### Development inside a Dev Container (recommended) +## Development inside a Dev Container (recommended) The easiest way to debug a program running inside a Docker container is via a dev container. This essentially allows you to run all of IntelliJ (or VSCode) inside the container, which enables debugging the code on Windows machines. @@ -14,7 +14,7 @@ you to run all of IntelliJ (or VSCode) inside the container, which enables debug This requires having Docker installed and running on your machine. To develop with IntelliJ, it also requires the full professional version (or a student license of it). The VSCode equivalent is free. -###### IntelliJ +### IntelliJ To do this in IntelliJ, navigate to `.devcontainer/devcontainer.json`. There should be an icon that pops up next to the opening curly brace. Click the icon, then select `Create Dev Container and Clone Sources...`. (Not to be confused @@ -36,12 +36,12 @@ and paste a link to the autograder GitHub repo (or your fork of it). The remaind `Build Container and Continue` is the same as above, except that to reopen the container after you've closed it, you'll need to open Gateway again and select the dev container from there. -###### VSCode +### VSCode Go fish🐟 These instructions are not included in this file. It should be possible to simply use VSCode's Dev Containers extension, though. -### Development inside WSL +## Development inside WSL If Docker doesn't work for some reason, you can use WSL. You'll be able to simply clone and run the autograder, except that everything in these instructions should be done via a WSL terminal _and_ inside a WSL directory. If you use a From 920bec23ab76465052a6cf11a4f2bac4376e7195 Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Mon, 28 Oct 2024 19:37:10 +0000 Subject: [PATCH 03/27] enhance: minor improvements and clarifications --- README.md | 15 +++++++-------- getting-started/getting-started.md | 15 +++++++-------- getting-started/linux.md | 5 ++++- getting-started/mac-os.md | 4 ++++ getting-started/macos.md | 1 - getting-started/windows.md | 9 ++++++--- 6 files changed, 28 insertions(+), 21 deletions(-) create mode 100644 getting-started/mac-os.md delete mode 100644 getting-started/macos.md diff --git a/README.md b/README.md index 5b7bfeb5e..eb2e7710d 100644 --- a/README.md +++ b/README.md @@ -46,13 +46,7 @@ property `db.url` is set to `db:3306` ## Development -First read the relevant OS-specific instructions: - -- [Windows](getting-started/windows.md) -- [Linux](getting-started/linux.md) -- [MacOS](getting-started/macos.md) - -Then follow the [Getting Started](getting-started/getting-started.md) page to Get Started! +New to autograder development? Follow the [Getting Started guide](getting-started/getting-started.md)! ### How to Contribute @@ -60,6 +54,11 @@ Here are a few tips for first projects or tasks to learn the autograder: - Review the Sequence/Class Diagrams (_coming soon_) and try creating one - Add documentation - Find a section of under-tested code and add some unit tests -- Take a look through the GitHub repo's Issues page and find one you like, especially ones labeled "good first issue" +- Take a look through the GitHub repo's [Issues](https://github.com/softwareconstruction240/autograder/issues) page +and find one you like, especially (but not limited to) ones labeled +["good first issue"](https://github.com/softwareconstruction240/autograder/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). + +It's also a good idea to read through the repo's +`CONTRIBUTING.md` ([COMING SOON](https://github.com/softwareconstruction240/autograder/issues/448)). Don't be afraid to submit a PR, and most importantly, just get stuck in! \ No newline at end of file diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index ba07dad1b..251b127cf 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -6,7 +6,7 @@ Operating System-specific instructions (read the applicable doc before continuin - [Windows](windows.md) - [Linux](linux.md) -- [MacOS](macos.md) +- [macOS](mac-os.md) ### Node/Yarn @@ -88,14 +88,13 @@ required). That decision is left to you. ### Canvas Integration To link the autograder with Canvas, you will need to generate a Canvas API key and set the autograder to the current -Course and Assignment ID numbers on Canvas. - -#### Canvas API Key - -A Canvas Authorization Key is required to link the project to Canvas. If you don't need Canvas integration, +Course and Assignment ID numbers on Canvas. If you don't need Canvas integration, `--canvas-token ` can be replaced with `--use-canvas false`, which mocks Canvas calls. Then you can skip this section. +#### Canvas API Key +A Canvas Authorization Key is required to link the project to Canvas. + To generate a Canvas API key: 1. Login to [Canvas](https://byu.instructure.com/) @@ -119,8 +118,8 @@ As of 'SUMMER 2024', the course number is `26822`. To ensure that the assignment IDs and rubric IDs/points are synced with Canvas, go to the `config` tab, select the button `Update using Canvas`, and select `Yes`. If there's a slight -issue, you may need to explore updating the course IDs manually, whether that be directly though the database or by -clicking the `Update Manually` in the `config` tab. +issue, you may need to explore updating the course IDs manually, whether that be directly though the database's +`configuration` table or by clicking `Update Manually` in the `config` tab. Additionally, if you want (not required), you can insert values into the `configuration` table manually (although the step above should do it automatically). [Here](db-insert-statements/insert-config-database.md) is the insert statement. diff --git a/getting-started/linux.md b/getting-started/linux.md index 71dfaa10e..91f0a6606 100644 --- a/getting-started/linux.md +++ b/getting-started/linux.md @@ -1 +1,4 @@ -Nothing here currently. \ No newline at end of file +# Special "Getting Started" instructions on Linux Machines + +There is currently no information specific to Linux. Follow the [getting started](getting-started.md) page +as-written. (If you know of anything to add here, submit a PR!) diff --git a/getting-started/mac-os.md b/getting-started/mac-os.md new file mode 100644 index 000000000..e9e430bdb --- /dev/null +++ b/getting-started/mac-os.md @@ -0,0 +1,4 @@ +# Special "Getting Started" instructions on macOS Machines + +There is currently no information specific to macOS. Follow the [getting started](getting-started.md) page +as-written. (If you know of anything to add here, submit a PR!) diff --git a/getting-started/macos.md b/getting-started/macos.md deleted file mode 100644 index 71dfaa10e..000000000 --- a/getting-started/macos.md +++ /dev/null @@ -1 +0,0 @@ -Nothing here currently. \ No newline at end of file diff --git a/getting-started/windows.md b/getting-started/windows.md index 14ea18dd2..5064bbbde 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -1,4 +1,4 @@ -# Windows +# Special "Getting Started" instructions on Windows Machines The autograder unfortunately won't work directly from Windows, so it must be run inside a Docker container (recommended) or inside WSL (possible but can be finicky). When running the autograder inside a Docker container, @@ -8,8 +8,11 @@ Either way, running your MySQL server locally on your Windows machine should wor ## Development inside a Dev Container (recommended) -The easiest way to debug a program running inside a Docker container is via a dev container. This essentially allows -you to run all of IntelliJ (or VSCode) inside the container, which enables debugging the code on Windows machines. +The easiest way to debug a program running inside a Docker container is via a "Dev Container," which is essentially +just a fancy term for a Docker container that's linked to an IDE. It essentially allows you to run your IDE inside the +container, which enables debugging the autograder code on Windows machines. How it works is IDE-specific; this document +provides instructions for the autograder using IntelliJ. Further reading can be +found [here](https://www.jetbrains.com/help/idea/connect-to-devcontainer.html). This requires having Docker installed and running on your machine. To develop with IntelliJ, it also requires the full professional version (or a student license of it). The VSCode equivalent is free. From 7a45c7ab43618f60fa45781da394c48767d2e98c Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Mon, 28 Oct 2024 19:50:55 +0000 Subject: [PATCH 04/27] enhance: improved intro to WSL --- getting-started/windows.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/getting-started/windows.md b/getting-started/windows.md index 5064bbbde..23605eaea 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -1,8 +1,9 @@ # Special "Getting Started" instructions on Windows Machines The autograder unfortunately won't work directly from Windows, so it must be run inside a Docker container -(recommended) or inside WSL (possible but can be finicky). When running the autograder inside a Docker container, -you will need to use a _Dev Container_ if you want to use IntelliJ's or VSCode's debugging tools. +(recommended) or inside WSL, the Windows Subsystem for Linux (possible but can be finicky). When running the autograder +inside a Docker container, you will need to use a _Dev Container_ if you want to use IntelliJ's or VSCode's debugging +tools. Either way, running your MySQL server locally on your Windows machine should work for the database. @@ -46,10 +47,22 @@ extension, though. ## Development inside WSL -If Docker doesn't work for some reason, you can use WSL. You'll be able to simply clone and run the autograder, except -that everything in these instructions should be done via a WSL terminal _and_ inside a WSL directory. If you use a -Windows directory, like Desktop/chess, you might run into file permissions errors. "Unix-like" shells, such as Git -Bash, will not work: it needs to be a true WSL terminal. +Note: this isn't the recommended option, and these instructions might not be maintained. + +WSL 2 (Windows Subsystem for Linux 2) is essentially a Linux kernel that's built into Windows, which means you'll be +able to simply clone and run the autograder as if you were running Linux. Development is fairly simple once set up, but +getting it set up for the autograder can be a bit finicky. + +*WARNING*: Everything in these instructions (including everything in `getting-started.md`) +should be done via a WSL terminal _and_ inside a WSL directory. "Unix-like" shells, such as Git Bash, will not work: +it needs to be a true WSL terminal. Similarly, all your autograder files should be cloned into WSL's own dedicated +file system. Yes, WSL can access your Windows files (via the `/mnt/c/` path), but if you use a Windows directory, +like Desktop/chess, you might run into file permissions errors. + +### Setup + +Install and configure WSL if needed. Instructions can be found +[here](https://learn.microsoft.com/en-us/windows/wsl/install). For the `--db-host` program argument, you can't simply use `localhost` (assuming your database is running on Windows), since that will refer to the WSL instance. Running `echo $(hostname)` from a WSL terminal will tell you what your From 96cccda5aa79482dd9ae59768ac85b0ae8fc97c1 Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Mon, 28 Oct 2024 19:56:09 +0000 Subject: [PATCH 05/27] rmv references to VSCode --- getting-started/windows.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/getting-started/windows.md b/getting-started/windows.md index 23605eaea..55eb1f80d 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -2,7 +2,7 @@ The autograder unfortunately won't work directly from Windows, so it must be run inside a Docker container (recommended) or inside WSL, the Windows Subsystem for Linux (possible but can be finicky). When running the autograder -inside a Docker container, you will need to use a _Dev Container_ if you want to use IntelliJ's or VSCode's debugging +inside a Docker container, you will need to use a _Dev Container_ if you want to use IntelliJ's debugging tools. Either way, running your MySQL server locally on your Windows machine should work for the database. @@ -15,12 +15,12 @@ container, which enables debugging the autograder code on Windows machines. How provides instructions for the autograder using IntelliJ. Further reading can be found [here](https://www.jetbrains.com/help/idea/connect-to-devcontainer.html). -This requires having Docker installed and running on your machine. To develop with IntelliJ, it also requires the full -professional version (or a student license of it). The VSCode equivalent is free. +This requires having Docker installed and running on your machine. It also requires the full +professional version of IntelliJ (or a student license of it). -### IntelliJ +### Setup -To do this in IntelliJ, navigate to `.devcontainer/devcontainer.json`. There should be an icon that pops up next to +Navigate to `.devcontainer/devcontainer.json`. There should be an icon that pops up next to the opening curly brace. Click the icon, then select `Create Dev Container and Clone Sources...`. (Not to be confused with `Mount Sources`, which doesn't quite work. If the Clone Sources option does not appear, see below.) This should pop up a dialog box that allows you to change a few options about the container. Look through them @@ -40,11 +40,6 @@ and paste a link to the autograder GitHub repo (or your fork of it). The remaind `Build Container and Continue` is the same as above, except that to reopen the container after you've closed it, you'll need to open Gateway again and select the dev container from there. -### VSCode - -Go fish🐟 These instructions are not included in this file. It should be possible to simply use VSCode's Dev Containers -extension, though. - ## Development inside WSL Note: this isn't the recommended option, and these instructions might not be maintained. From b7bdade400b8ac8d40c688a5d78192f7b58092c1 Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Mon, 28 Oct 2024 20:00:49 +0000 Subject: [PATCH 06/27] rmv empty "os-specific instructions" files --- getting-started/getting-started.md | 10 +++++----- getting-started/linux.md | 4 ---- getting-started/mac-os.md | 4 ---- 3 files changed, 5 insertions(+), 13 deletions(-) delete mode 100644 getting-started/linux.md delete mode 100644 getting-started/mac-os.md diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index 251b127cf..a0428271b 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -2,11 +2,11 @@ ## Pre-requisites -Operating System-specific instructions (read the applicable doc before continuing): - -- [Windows](windows.md) -- [Linux](linux.md) -- [macOS](mac-os.md) +> [!IMPORTANT] +> The autograder unfortunately requires special setup instructions +> in order to operate on **Windows machines**. +> +> Read [Getting Started on Windows](windows.md) before continuing. ### Node/Yarn diff --git a/getting-started/linux.md b/getting-started/linux.md deleted file mode 100644 index 91f0a6606..000000000 --- a/getting-started/linux.md +++ /dev/null @@ -1,4 +0,0 @@ -# Special "Getting Started" instructions on Linux Machines - -There is currently no information specific to Linux. Follow the [getting started](getting-started.md) page -as-written. (If you know of anything to add here, submit a PR!) diff --git a/getting-started/mac-os.md b/getting-started/mac-os.md deleted file mode 100644 index e9e430bdb..000000000 --- a/getting-started/mac-os.md +++ /dev/null @@ -1,4 +0,0 @@ -# Special "Getting Started" instructions on macOS Machines - -There is currently no information specific to macOS. Follow the [getting started](getting-started.md) page -as-written. (If you know of anything to add here, submit a PR!) From b2251c3ea1182ade955508ae1284f98c72ddc714 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Mon, 28 Oct 2024 17:00:47 -0600 Subject: [PATCH 07/27] Leverage GitHub alerts for emphasis of warnings --- README.md | 5 +++-- getting-started/windows.md | 16 ++++++++++------ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index eb2e7710d..1349f88fd 100644 --- a/README.md +++ b/README.md @@ -41,8 +41,9 @@ docker compose --profile with-db up -d docker compose up -d ``` -Note, if you are using the docker MySQL database, ensure that in `src/main/resources/db.properties` the -property `db.url` is set to `db:3306` +> [!NOTE] +> If you are using the docker MySQL database, ensure that in +> `src/main/resources/db.properties` the property `db.url` is set to `db:3306`. ## Development diff --git a/getting-started/windows.md b/getting-started/windows.md index 55eb1f80d..8da96f426 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -42,17 +42,21 @@ need to open Gateway again and select the dev container from there. ## Development inside WSL -Note: this isn't the recommended option, and these instructions might not be maintained. +> [!CAUTION] +> WSL isn't the recommended option, and these instructions might not be maintained. WSL 2 (Windows Subsystem for Linux 2) is essentially a Linux kernel that's built into Windows, which means you'll be able to simply clone and run the autograder as if you were running Linux. Development is fairly simple once set up, but getting it set up for the autograder can be a bit finicky. -*WARNING*: Everything in these instructions (including everything in `getting-started.md`) -should be done via a WSL terminal _and_ inside a WSL directory. "Unix-like" shells, such as Git Bash, will not work: -it needs to be a true WSL terminal. Similarly, all your autograder files should be cloned into WSL's own dedicated -file system. Yes, WSL can access your Windows files (via the `/mnt/c/` path), but if you use a Windows directory, -like Desktop/chess, you might run into file permissions errors. +> [!WARNING] +> Everything in these instructions (including everything in `getting-started.md`) +> should be done via a WSL terminal _and_ inside a WSL directory. +> +> "Unix-like" shells, such as Git Bash, will not work: it needs to be a true WSL terminal. +> Similarly, all your autograder files should be cloned into WSL's own dedicated file system. +> Yes, WSL can access your Windows files (via the `\mnt\c\` path), but with the use of a Windows +> directory like `C:\Desktop\chess`, you might face to file permissions errors. ### Setup From 564c4b7a7b8d1dbc883d98169436625bdcbef1a3 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Mon, 28 Oct 2024 17:01:14 -0600 Subject: [PATCH 08/27] Adjust whitespace --- README.md | 4 ++-- getting-started/windows.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1349f88fd..fb413bbe7 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ docker compose up -d ``` > [!NOTE] -> If you are using the docker MySQL database, ensure that in +> If you are using the docker MySQL database, ensure that in > `src/main/resources/db.properties` the property `db.url` is set to `db:3306`. ## Development @@ -62,4 +62,4 @@ and find one you like, especially (but not limited to) ones labeled It's also a good idea to read through the repo's `CONTRIBUTING.md` ([COMING SOON](https://github.com/softwareconstruction240/autograder/issues/448)). -Don't be afraid to submit a PR, and most importantly, just get stuck in! \ No newline at end of file +Don't be afraid to submit a PR, and most importantly, just get stuck in! diff --git a/getting-started/windows.md b/getting-started/windows.md index 8da96f426..a3d0a62fc 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -72,4 +72,4 @@ By default, MySQL users have "Limit to Host Matching" set to `localhost`, which WSL virtual machine. You will have to expand this in MySQLWorkbench (under Server, click "Users and Privileges"). The easiest way is to change it to `%`, which allows all hostnames (but it is highly recommended that you only do this for a new user with restricted privileges, rather than using root). Another option is to run `wsl hostname -I` in PowerShell -to determine the WSL instance's IP address, then simply hardcode that, but this IP may change when WSL restarts. \ No newline at end of file +to determine the WSL instance's IP address, then simply hardcode that, but this IP may change when WSL restarts. From 0a55bb57febe0b908a947c7755d6239d65fb546f Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Mon, 28 Oct 2024 17:01:38 -0600 Subject: [PATCH 09/27] Adjust language of intro to WSL --- getting-started/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/windows.md b/getting-started/windows.md index a3d0a62fc..a68b1becd 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -1,7 +1,7 @@ # Special "Getting Started" instructions on Windows Machines The autograder unfortunately won't work directly from Windows, so it must be run inside a Docker container -(recommended) or inside WSL, the Windows Subsystem for Linux (possible but can be finicky). When running the autograder +(recommended) or inside WSL, the Windows Subsystem for Linux (not recommended). When running the autograder inside a Docker container, you will need to use a _Dev Container_ if you want to use IntelliJ's debugging tools. From 58fcbf72a755e93f90a002f21b723584ff7b1af6 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Mon, 28 Oct 2024 17:27:56 -0600 Subject: [PATCH 10/27] Convert additional note to GitHub alert --- getting-started/getting-started.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index a0428271b..273c63714 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -29,9 +29,10 @@ docker compose up db -d ## Getting Started -NOTE: These instructions will help you set up this project in IntelliJ. -If there are any holes or gaps in the instructions, please submit a new pull request -to preserve the learned knowledge for future generations. +> [!NOTE] +> These instructions will help you set up this project in IntelliJ. +> If there are any holes or gaps in the instructions, please submit a new pull request +> to preserve the learned knowledge for future generations. 1. Clone the repo onto your local machine. 2. Ensure that you are using the latest version of JVM. The system currently requires version 21+. From 6223a4a2ee919b0ee85900081e517d155efd9bc9 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Mon, 28 Oct 2024 17:31:23 -0600 Subject: [PATCH 11/27] Reorder to place notes together --- getting-started/windows.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/getting-started/windows.md b/getting-started/windows.md index a68b1becd..bcc062dd1 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -45,10 +45,6 @@ need to open Gateway again and select the dev container from there. > [!CAUTION] > WSL isn't the recommended option, and these instructions might not be maintained. -WSL 2 (Windows Subsystem for Linux 2) is essentially a Linux kernel that's built into Windows, which means you'll be -able to simply clone and run the autograder as if you were running Linux. Development is fairly simple once set up, but -getting it set up for the autograder can be a bit finicky. - > [!WARNING] > Everything in these instructions (including everything in `getting-started.md`) > should be done via a WSL terminal _and_ inside a WSL directory. @@ -58,6 +54,10 @@ getting it set up for the autograder can be a bit finicky. > Yes, WSL can access your Windows files (via the `\mnt\c\` path), but with the use of a Windows > directory like `C:\Desktop\chess`, you might face to file permissions errors. +WSL 2 (Windows Subsystem for Linux 2) is essentially a Linux kernel that's built into Windows, which means you'll be +able to simply clone and run the autograder as if you were running Linux. Development is fairly simple once set up, but +getting it set up for the autograder can be a bit finicky. + ### Setup Install and configure WSL if needed. Instructions can be found From 7a1708dc9d87cb03baf4cbf91fba2b7a0ddcb8ab Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Mon, 28 Oct 2024 17:34:58 -0600 Subject: [PATCH 12/27] Break long paragraphs into ordered lists of instructions --- getting-started/windows.md | 62 ++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 19 deletions(-) diff --git a/getting-started/windows.md b/getting-started/windows.md index bcc062dd1..84aa58f40 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -20,25 +20,49 @@ professional version of IntelliJ (or a student license of it). ### Setup -Navigate to `.devcontainer/devcontainer.json`. There should be an icon that pops up next to -the opening curly brace. Click the icon, then select `Create Dev Container and Clone Sources...`. (Not to be confused -with `Mount Sources`, which doesn't quite work. If the Clone Sources option does not appear, see below.) This should -pop up a dialog box that allows you to change a few options about the container. Look through them -and change what you need, then hit the `Build Container and Continue` button. Wait for IntelliJ and Docker to build -everything. You may need to click a few buttons along the way. Eventually a new IntelliJ window will pop up from the -dev container. Follow the [Getting Started](getting-started.md) steps with the new window. -Use `host.docker.internal` as your db-host argument; this tells docker to look for the database on your local Windows -machine rather than inside the container. To reopen the container after you've closed it, navigate to the -`.devcontainer/devcontainer.json` file again, click the icon, and select `Show Dev Containers`. Select the container -and it should reopen the second IntelliJ. If nothing appears, make sure the docker engine is running -(perhaps by opening Docker Desktop). - -If you don't see an option to `Clone Sources`, you can do the same thing via JetBrains Gateway. Download and install -it if you haven't already. (Installing via JetBrains Toolbox is probably the easiest way.) Open Gateway, select -`Dev Containers`, and click `New Dev Container`. Choose `From VCS Project`, select Intellij IDEA from the dropdown, -and paste a link to the autograder GitHub repo (or your fork of it). The remainder of the setup after clicking -`Build Container and Continue` is the same as above, except that to reopen the container after you've closed it, you'll -need to open Gateway again and select the dev container from there. +#### Initially Creating the Dev Container + +To setup your dev container for the first time: +1. Navigate to `.devcontainer/devcontainer.json` +2. There should be an icon that pops up next to the opening curly brace +3. Click the icon, then select `Create Dev Container and Clone Sources...`. (Not to be confused +with `Mount Sources`, which doesn't quite work.) + - This should pop up a dialog box that allows you to change a few options about the container. + - If the "Clone Sources" option does not appear, see [No Clone Sources](#no-clone-sources). + - Look through them and change what you need, then hit the `Build Container and Continue` button. +4. Wait for IntelliJ and Docker to build everything + - You may need to click a few buttons along the way. + - Eventually a new IntelliJ window will pop up from the dev container. +5. Follow the [Getting Started](getting-started.md) steps with the new window, with the following notes: + - Use `host.docker.internal` as your db-host argument; this tells docker to look for the + database on your local Windows machine rather than inside the container. + +#### Reopening the Dev Container + +To reopen the container after you've closed it: +1. Navigate to the `.devcontainer/devcontainer.json` file again, and click the icon +2. select `Show Dev Containers` +3. Select the container + - it should reopen the second IntelliJ. + - If nothing appears, make sure the docker engine is running (perhaps by opening Docker Desktop). + +#### Alternative Path To Create A Dev Container + +> [!NOTE] +> If you follow these instructions to create your Dev Container, you will also need +> an alternative path to reopen the dev container.\ +> Reopen your Dev Container by starting in the Gateway tool. + +If you don't see an option to `Clone Sources`, you can do the same thing via JetBrains Gateway. +1. Download and install JetBrains Gateway if you haven't already. + - Installing via JetBrains Toolbox is probably the easiest way. +2. Open Gateway, +3. Select `Dev Containers` +4. Click `New Dev Container` +5. Choose `From VCS Project` +6. Select "Intellij IDEA" from the dropdown +7. Paste a link to the autograder GitHub repo (or your fork of it) +8. Return to your previous place to continue setting the Dev Container ## Development inside WSL From 9c392ccf68c613de838accc80018070cdc8fd2e0 Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Tue, 29 Oct 2024 01:20:44 +0000 Subject: [PATCH 13/27] fix: update info about MySQL permissions --- getting-started/getting-started.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index a0428271b..cad4cd12a 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -82,8 +82,9 @@ been filled in with default values. Update these as needed to match your environ ``` While you can use any root user credentials to access the MySQL database, you may be interested in creating -a special login for this project with restricted privileges (DELETE and CREATE USER administrator privileges are -required). That decision is left to you. +a special login for this project. That decision is left to you. If you do create a different user, however, it will +need nearly root-level permissions in any case (enough to be able to create a new database, then create a "student" +user and `GRANT ALL` privileges to them for that database). The exact requirements are not listed here. ### Canvas Integration From 21311108892ea4e4c05c31f1852502d0558c2dbd Mon Sep 17 00:00:00 2001 From: ThanGerlek Date: Tue, 29 Oct 2024 01:37:25 +0000 Subject: [PATCH 14/27] minor typo fixes --- getting-started/windows.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/getting-started/windows.md b/getting-started/windows.md index 84aa58f40..d4266f169 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -22,7 +22,7 @@ professional version of IntelliJ (or a student license of it). #### Initially Creating the Dev Container -To setup your dev container for the first time: +To set up your dev container for the first time: 1. Navigate to `.devcontainer/devcontainer.json` 2. There should be an icon that pops up next to the opening curly brace 3. Click the icon, then select `Create Dev Container and Clone Sources...`. (Not to be confused @@ -41,9 +41,9 @@ with `Mount Sources`, which doesn't quite work.) To reopen the container after you've closed it: 1. Navigate to the `.devcontainer/devcontainer.json` file again, and click the icon -2. select `Show Dev Containers` +2. Select `Show Dev Containers` 3. Select the container - - it should reopen the second IntelliJ. + - It should reopen the second IntelliJ. - If nothing appears, make sure the docker engine is running (perhaps by opening Docker Desktop). #### Alternative Path To Create A Dev Container @@ -62,7 +62,7 @@ If you don't see an option to `Clone Sources`, you can do the same thing via Jet 5. Choose `From VCS Project` 6. Select "Intellij IDEA" from the dropdown 7. Paste a link to the autograder GitHub repo (or your fork of it) -8. Return to your previous place to continue setting the Dev Container +8. Continue setting up the Dev Container with steps 4 and 5 above ## Development inside WSL @@ -76,7 +76,7 @@ If you don't see an option to `Clone Sources`, you can do the same thing via Jet > "Unix-like" shells, such as Git Bash, will not work: it needs to be a true WSL terminal. > Similarly, all your autograder files should be cloned into WSL's own dedicated file system. > Yes, WSL can access your Windows files (via the `\mnt\c\` path), but with the use of a Windows -> directory like `C:\Desktop\chess`, you might face to file permissions errors. +> directory like `C:\Desktop\chess`, you might face file permissions errors. WSL 2 (Windows Subsystem for Linux 2) is essentially a Linux kernel that's built into Windows, which means you'll be able to simply clone and run the autograder as if you were running Linux. Development is fairly simple once set up, but From 002f9f07b54dea902699ae72b11c801e9841ea4c Mon Sep 17 00:00:00 2001 From: Nathaniel Gerlek Date: Mon, 28 Oct 2024 19:34:55 -0700 Subject: [PATCH 15/27] qualified WSL as not recommended unless already familiar --- getting-started/windows.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/getting-started/windows.md b/getting-started/windows.md index d4266f169..81ef9bcce 100644 --- a/getting-started/windows.md +++ b/getting-started/windows.md @@ -1,9 +1,9 @@ # Special "Getting Started" instructions on Windows Machines The autograder unfortunately won't work directly from Windows, so it must be run inside a Docker container -(recommended) or inside WSL, the Windows Subsystem for Linux (not recommended). When running the autograder -inside a Docker container, you will need to use a _Dev Container_ if you want to use IntelliJ's debugging -tools. +(recommended) or inside WSL, the Windows Subsystem for Linux (not recommended unless you're already familiar with WSL). +When running the autograder inside a Docker container, you will need to use a _Dev Container_ if you want to use +IntelliJ's debugging tools. Either way, running your MySQL server locally on your Windows machine should work for the database. From 2ab91fc7dc845d9e401c43356be6ca16d60b5a12 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Tue, 29 Oct 2024 08:28:30 -0600 Subject: [PATCH 16/27] Update README.md Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fb413bbe7..ecfef17ab 100644 --- a/README.md +++ b/README.md @@ -62,4 +62,4 @@ and find one you like, especially (but not limited to) ones labeled It's also a good idea to read through the repo's `CONTRIBUTING.md` ([COMING SOON](https://github.com/softwareconstruction240/autograder/issues/448)). -Don't be afraid to submit a PR, and most importantly, just get stuck in! +Don't be afraid to submit a PR, and most importantly, just get sucked in! From 37fb50c78e17919b55621bd4497e2ea24f97ce10 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Tue, 29 Oct 2024 09:20:24 -0600 Subject: [PATCH 17/27] Clean up trailing whitespace --- getting-started/getting-started.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index 89d28942c..bc85f01e3 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -10,7 +10,7 @@ ### Node/Yarn -The frontend is built using Vue.js. To run the frontend, you will need to have `yarn` (see +The frontend is built using Vue.js. To run the frontend, you will need to have `yarn` (see [installing yarn](https://yarnpkg.com/getting-started/install)). After installing `Node` if necessary, run the following to enable `yarn` globally (sudo may be required): @@ -20,7 +20,7 @@ corepack enable ### Backend Database -You can run the database either locally with your own MySQL server or inside a Docker container. To run the database +You can run the database either locally with your own MySQL server or inside a Docker container. To run the database inside its own Docker container, run the following in the root of the project: ```bash @@ -84,7 +84,7 @@ been filled in with default values. Update these as needed to match your environ While you can use any root user credentials to access the MySQL database, you may be interested in creating a special login for this project. That decision is left to you. If you do create a different user, however, it will -need nearly root-level permissions in any case (enough to be able to create a new database, then create a "student" +need nearly root-level permissions in any case (enough to be able to create a new database, then create a "student" user and `GRANT ALL` privileges to them for that database). The exact requirements are not listed here. ### Canvas Integration @@ -120,7 +120,7 @@ As of 'SUMMER 2024', the course number is `26822`. To ensure that the assignment IDs and rubric IDs/points are synced with Canvas, go to the `config` tab, select the button `Update using Canvas`, and select `Yes`. If there's a slight -issue, you may need to explore updating the course IDs manually, whether that be directly though the database's +issue, you may need to explore updating the course IDs manually, whether that be directly though the database's `configuration` table or by clicking `Update Manually` in the `config` tab. Additionally, if you want (not required), you can insert values into the `configuration` table manually @@ -128,8 +128,8 @@ Additionally, if you want (not required), you can insert values into the `config ### Environment Variables -If you are running Loki locally (not required), then you must set the `LOKI_URL` environment variable. The value can be -either `localhost:3100` (if you are NOT using docker to develop the app) or `loki:3100` (if you are using docker to +If you are running Loki locally (not required), then you must set the `LOKI_URL` environment variable. The value can be +either `localhost:3100` (if you are NOT using docker to develop the app) or `loki:3100` (if you are using docker to develop the app). ### Loading the Configuration Related Tables From bb5b023996af1c0023cbd52b6171b1011d4a87e2 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Tue, 29 Oct 2024 09:59:00 -0600 Subject: [PATCH 18/27] Expand surface area and adjust style of links --- getting-started/getting-started.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index bc85f01e3..a14560328 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -124,7 +124,7 @@ issue, you may need to explore updating the course IDs manually, whether that be `configuration` table or by clicking `Update Manually` in the `config` tab. Additionally, if you want (not required), you can insert values into the `configuration` table manually -(although the step above should do it automatically). [Here](db-insert-statements/insert-config-database.md) is the insert statement. +(although the step above should do it automatically). See the [insert `config` SQL statements](db-insert-statements/insert-config-database.md). ### Environment Variables @@ -135,9 +135,8 @@ develop the app). ### Loading the Configuration Related Tables As of right now, you will need to manually insert the correct values into the `rubric_config` table before being -able to run the actual grading on the autograder. [Here](db-insert-statements/insert-rubric-database.md) is an insert statement for that. +able to run the actual grading on the autograder. See the [insert `rubric_config` SQL statements](db-insert-statements/insert-rubric-database.md). #### Updating from the Old Rubric Config Table -If you have the autograder prior to 'SUMMER 2024', [this SQL statement](db-insert-statements/update-rubric-database.md) should do the job of updating -the `rubric_config` table. +If you had the autograder prior to 'SUMMER 2024', see the [update `rubric_config` SQL statements](db-insert-statements/update-rubric-database.md). From 2e140a1521ecd0db9685db1cfc27d75c218629d1 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Tue, 29 Oct 2024 10:01:11 -0600 Subject: [PATCH 19/27] Expand and elaborate getting-started.md instructions with list formatting --- getting-started/getting-started.md | 39 ++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index a14560328..e35549c3e 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -35,7 +35,8 @@ docker compose up db -d > to preserve the learned knowledge for future generations. 1. Clone the repo onto your local machine. -2. Ensure that you are using the latest version of JVM. The system currently requires version 21+. +2. Ensure that you are using the latest version of JVM. + - The system currently requires version 21+. 3. Use `yarn` to install all dependencies. This must be done from the _front end_ root folder. (If using WSL, run this from an actual WSL terminal. Windows-based shells, even POSIX ones, won't install the correct files.) ```bash @@ -63,7 +64,14 @@ docker compose up db -d cd src/main/resources/frontend yarn dev ``` - - Load the configuration related tables by referencing the [section below](#loading-the-configuration-related-tables) +7. (Optional) Setup [Canvas Integration](#canvas-integration) + - This is only required if you hope to transfer data to Canvas during your workflow; + - otherwise, use the `--use-canvas false` program argument and skip this step. +8. (Optional) Setup the [Environment Variables](#environment-variables) + - This is only required when running `Loki` locally; + - otherwise, skip this step. +9. Load the [configuration related tables](#loading-the-configuration-related-tables) + - This is required. ### Program Arguments @@ -89,10 +97,11 @@ user and `GRANT ALL` privileges to them for that database). The exact requiremen ### Canvas Integration -To link the autograder with Canvas, you will need to generate a Canvas API key and set the autograder to the current -Course and Assignment ID numbers on Canvas. If you don't need Canvas integration, -`--canvas-token ` can be replaced with `--use-canvas false`, which mocks Canvas calls. Then you can -skip this section. +To link the autograder with Canvas, you will need to generate a Canvas API key and set the autograder to the current +Course and Assignment ID numbers on Canvas. + +If you don't need Canvas integration, `--canvas-token ` can be replaced with `--use-canvas false`, +which mocks Canvas calls. Then, you can skip this section. #### Canvas API Key A Canvas Authorization Key is required to link the project to Canvas. @@ -110,13 +119,14 @@ To generate a Canvas API key: #### Canvas Data -To get the correct Canvas course ID, go to Canvas and select the current CS 240 course. The URL should -change to something like `https://byu.instructure.com/courses/` where `` is the number -you need to use inside the `configuration` table. You can set this by logging into the autograder and using the -`Update Manually` button in the `Config` tab. Click that button and modify the `Course Number` input and then -click `Submit`. - -As of 'SUMMER 2024', the course number is `26822`. +To get the correct Canvas course ID: +1. Go to Canvas and select the current CS 240 course +2. The URL should change to something like `https://byu.instructure.com/courses/` +3. Extract `` from the url + 4. This is the number that needs to end up in the configuration table +5. You can set this by logging into the autograder and using the + `Update Manually` button in the `Config` tab. Click that button and modify the `Course Number` input and then + click `Submit`. To ensure that the assignment IDs and rubric IDs/points are synced with Canvas, go to the `config` tab, select the button `Update using Canvas`, and select `Yes`. If there's a slight @@ -137,6 +147,9 @@ develop the app). As of right now, you will need to manually insert the correct values into the `rubric_config` table before being able to run the actual grading on the autograder. See the [insert `rubric_config` SQL statements](db-insert-statements/insert-rubric-database.md). +Insert the commands using a [SQL client](https://github.com/softwareconstruction240/softwareconstruction/blob/main/instruction/mysql/mysql.md#sql-clients) +of your choice on your machine (MySql Shell, SQLWorkbench, or Intelli-J's built in tools). + #### Updating from the Old Rubric Config Table If you had the autograder prior to 'SUMMER 2024', see the [update `rubric_config` SQL statements](db-insert-statements/update-rubric-database.md). From 34e9cfe26ba66ac25763216963f98b9b28a776de Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Tue, 29 Oct 2024 10:42:15 -0600 Subject: [PATCH 20/27] Additional content and formatting adjustments --- getting-started/getting-started.md | 35 +++++++++++++++++------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index e35549c3e..6c15a8f0c 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -119,22 +119,27 @@ To generate a Canvas API key: #### Canvas Data -To get the correct Canvas course ID: +To update Canvas course ID: 1. Go to Canvas and select the current CS 240 course 2. The URL should change to something like `https://byu.instructure.com/courses/` 3. Extract `` from the url - 4. This is the number that needs to end up in the configuration table -5. You can set this by logging into the autograder and using the - `Update Manually` button in the `Config` tab. Click that button and modify the `Course Number` input and then - click `Submit`. + - This is the number that needs to end up in the configuration table +4. You can set this by logging into the autograder and using the `Update Manually` button in the `Config` tab. + 1. Click that button and modify the `Course Number` input + 2. Click `Submit` -To ensure that the assignment IDs and rubric IDs/points are synced with Canvas, go -to the `config` tab, select the button `Update using Canvas`, and select `Yes`. If there's a slight -issue, you may need to explore updating the course IDs manually, whether that be directly though the database's -`configuration` table or by clicking `Update Manually` in the `config` tab. +To ensure that the assignment IDs and rubric IDs/points are synced with Canvas: +1. Go to the `config` tab of the AutoGrader +2. Select the button `Update using Canvas` +3. Select `Yes` + +> [!NOTE] +> If there's an issue with the process, you may need to explore updating the course IDs manually. +> This can be done directly though the database's `configuration` table or +> by clicking `Update Manually` in the `config` tab. Additionally, if you want (not required), you can insert values into the `configuration` table manually -(although the step above should do it automatically). See the [insert `config` SQL statements](db-insert-statements/insert-config-database.md). +(although the step above should do it automatically). See [Insert `config` SQL Statements](db-insert-statements/insert-config-database.md). ### Environment Variables @@ -144,12 +149,12 @@ develop the app). ### Loading the Configuration Related Tables +> [!IMPORTANT] +> If you had the autograder prior to 'SUMMER 2024', there is a separate "update" set of SQL commands to use.\ +> See [Update `rubric_config` SQL Statements](db-insert-statements/update-rubric-database.md). + As of right now, you will need to manually insert the correct values into the `rubric_config` table before being -able to run the actual grading on the autograder. See the [insert `rubric_config` SQL statements](db-insert-statements/insert-rubric-database.md). +able to run the actual grading on the autograder. See [Insert `rubric_config` SQL Statements](db-insert-statements/insert-rubric-database.md). Insert the commands using a [SQL client](https://github.com/softwareconstruction240/softwareconstruction/blob/main/instruction/mysql/mysql.md#sql-clients) of your choice on your machine (MySql Shell, SQLWorkbench, or Intelli-J's built in tools). - -#### Updating from the Old Rubric Config Table - -If you had the autograder prior to 'SUMMER 2024', see the [update `rubric_config` SQL statements](db-insert-statements/update-rubric-database.md). From b521fa58855de6b3232949a9d2c002952c317c29 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Tue, 29 Oct 2024 10:54:53 -0600 Subject: [PATCH 21/27] Add contextual and explanatory headers to the SQL statement pages --- .../insert-config-database.md | 17 +++++++++++++-- .../insert-rubric-database.md | 14 ++++++++++++- .../update-rubric-database.md | 21 +++++++++++++++---- 3 files changed, 45 insertions(+), 7 deletions(-) diff --git a/getting-started/db-insert-statements/insert-config-database.md b/getting-started/db-insert-statements/insert-config-database.md index d48906904..bec533466 100644 --- a/getting-started/db-insert-statements/insert-config-database.md +++ b/getting-started/db-insert-statements/insert-config-database.md @@ -1,5 +1,18 @@ -UPDATED AS OF 'SUMMER 2024'. Note that the primary thing that needs to be updated is the value of the `COURSE_NUMBER` -and each of the assignment numbers. +# Insert `config` SQL Statements + +This guide is primarily responsible for initializing the `configuration` table, +assuming that the table begins in an empty state. + +## Updating Guide + +The primary things that needs to be updated on an ongoing basis are: +1. The value of the `COURSE_NUMBER` +2. Each of the assignment numbers + + +## Statements +> [!NOTE] +> Updated as of **SUMMER 2024** ```mysql INSERT INTO configuration (config_key, value) VALUES diff --git a/getting-started/db-insert-statements/insert-rubric-database.md b/getting-started/db-insert-statements/insert-rubric-database.md index 5057aa45b..0a04c58d0 100644 --- a/getting-started/db-insert-statements/insert-rubric-database.md +++ b/getting-started/db-insert-statements/insert-rubric-database.md @@ -1,4 +1,16 @@ -UPDATED AS OF 'SUMMER 2024'. Note that the primary thing that needs to be updated here is the `rubric_id` column. +# Insert `rubric` SQL Statements + +This guide is primarily responsible for initializing the `rubric_config` table, +assuming that the table begins in an empty state. + +## Updating Guide + +The primary things that needs to be updated on an ongoing basis are: +1. Values in the `rubric_id` column + +## Statements +> [!NOTE] +> Updated as of **SUMMER 2024** ```mysql INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) VALUES diff --git a/getting-started/db-insert-statements/update-rubric-database.md b/getting-started/db-insert-statements/update-rubric-database.md index 133df80d1..a48a819f9 100644 --- a/getting-started/db-insert-statements/update-rubric-database.md +++ b/getting-started/db-insert-statements/update-rubric-database.md @@ -1,7 +1,20 @@ -If you have the autograder prior to 'SUMMER 2024', the following SQL should do the job of updating -the `rubric_config` table: +# Updating `rubric` SQL Statements + +This guide is primarily responsible for updating the `rubric_config` table +when it has already been initialized from [Inserting Rubric SQL Statements](./insert-rubric-database.md). + +These statements only apply to you if you had set up the AutoGrader prior to the +"last updated" date of this guide. + +## Updating Guide + +The primary things that needs to be updated on an ongoing basis are: +1. _Depends on any changes to the `rubric_config` schema_ + +## Statements +> [!NOTE] +> Updated as of **SUMMER 2024** -UPDATED AS OF 'SUMMER 2024' ```mysql ALTER TABLE rubric_config ADD rubric_id VARCHAR(15); -- could be ten as no rubric ids so far are longer than 10, but just in case @@ -37,4 +50,4 @@ UPDATE rubric_config SET rubric_id = '90348_899' WHERE phase = 'Phase6' and type UPDATE rubric_config SET rubric_id = '90348_3792' WHERE phase = 'Phase6' and type = 'QUALITY'; INSERT INTO rubric_config (phase, type, category, criteria, points, rubric_id) VALUES ('Phase6', 'GIT_COMMITS', 'Git Commits', 'Necessary commit amount', 0, '90348_9048'); -``` \ No newline at end of file +``` From 1ef3d9868db0595202b957d6ef28fec2122bda51 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Tue, 29 Oct 2024 11:03:15 -0600 Subject: [PATCH 22/27] Add new feature tip in Insert Config Database --- .../db-insert-statements/insert-config-database.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/getting-started/db-insert-statements/insert-config-database.md b/getting-started/db-insert-statements/insert-config-database.md index bec533466..f45e91b12 100644 --- a/getting-started/db-insert-statements/insert-config-database.md +++ b/getting-started/db-insert-statements/insert-config-database.md @@ -3,6 +3,10 @@ This guide is primarily responsible for initializing the `configuration` table, assuming that the table begins in an empty state. +> [!TIP] +> The configuration table can _more easily_ be configured with programmatic tools built in to the AutoGrader. +> Find these tools in AutoGrader > Config > Update using Canvas. + ## Updating Guide The primary things that needs to be updated on an ongoing basis are: From e5bc053e08be64ba9e7a6a13313400085b206ab1 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Thu, 31 Oct 2024 10:33:39 -0600 Subject: [PATCH 23/27] Update getting-started.md Streamline instructions into a single cohesive sequence --- getting-started/getting-started.md | 147 ++++++++++++++++++----------- 1 file changed, 93 insertions(+), 54 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index 6c15a8f0c..0c4254c2b 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -27,59 +27,74 @@ inside its own Docker container, run the following in the root of the project: docker compose up db -d ``` -## Getting Started +While you can use any root user credentials to access the MySQL database, you may be interested in creating +a special login for this project. That decision is left to you. If you do create a different user, however, it will +need nearly root-level permissions in any case (enough to be able to create a new database, then create a "student" +user and `GRANT ALL` privileges to them for that database). The exact requirements are not listed here. + +## Quickstart Instructions > [!NOTE] -> These instructions will help you set up this project in IntelliJ. -> If there are any holes or gaps in the instructions, please submit a new pull request +> These instructions will help you set up this project in IntelliJ.\ +> If there are any holes or gaps in the instructions, please submit a new pull request\ > to preserve the learned knowledge for future generations. -1. Clone the repo onto your local machine. -2. Ensure that you are using the latest version of JVM. - - The system currently requires version 21+. -3. Use `yarn` to install all dependencies. This must be done from the _front end_ root folder. (If using WSL, run this - from an actual WSL terminal. Windows-based shells, even POSIX ones, won't install the correct files.) - ```bash - cd src/main/resources/frontend - yarn - ``` -4. Setup "Server" _Run Configuration_ - - Navigate to the server file: `src/main/java/edu/byu/cs/server/Server.java` - - Click the "Run" button to run `Server.main()` - - This will give you a _Run Configuration_ that you can modify in the following steps. -5. Set up [program arguments](#program-arguments) - - Reference the [subtitle below](#program-arguments) for the list of required arguments - - Prepare the values you will use for each argument - - Put them all onto a single line, with each argument name followed by its value - - Ex. `--arg-1 arg1Val --arg-2 arg2Val` - - Edit the "Server" run configuration - - Paste in the single line of parameters to the line titled "Program arguments" - - Save & apply the changes -6. **Run the Autograder Locally** - - Run your "Server" run configuration - - Run the frontend by referencing the code below. In the case you are running on the - Autograder inside a dev container, you may need to add the `--host` option at the - end of the `yarn dev` command (`yarn dev --host`). - ```bash - cd src/main/resources/frontend - yarn dev - ``` -7. (Optional) Setup [Canvas Integration](#canvas-integration) - - This is only required if you hope to transfer data to Canvas during your workflow; - - otherwise, use the `--use-canvas false` program argument and skip this step. -8. (Optional) Setup the [Environment Variables](#environment-variables) - - This is only required when running `Loki` locally; - - otherwise, skip this step. -9. Load the [configuration related tables](#loading-the-configuration-related-tables) - - This is required. - -### Program Arguments +### 1. Clone the Repo onto your local machine + +Any variation of the following will work. +```shell +git clone https://github.com/softwareconstruction240/autograder.git +``` + +Additionally, you can also leverage Intelli-J's "File > New > New Project from Version Control" +feature which will do it for you given a GitHub link. + +### 2. Use the latest version of the JVM +The system currently requires version **21+**. + +Go fish🐟 Specific instructions to update are not included here. + +### 3. Install front end dependencies + +> [!CAUTION] +> **Windows** If using WSL, run this from an actual WSL terminal.\ +> Windows-based shells, even POSIX ones, won't install the correct files. + +Use `yarn` to install all dependencies. This must be done from the _front end_ root folder. + ```bash + cd src/main/resources/frontend + yarn + ``` + +### 4. Setup "Server" _Run Configuration_ + +Do the following steps: +1. Navigate to the server file: `src/main/java/edu/byu/cs/server/Server.java` +2. Click the "Run" button to run `Server.main()` +3. This will give you a _Run Configuration_ that you can modify in the following steps. + + +### 5. Set up Program Arguments For both deployment and development, the following program arguments are required to be set. Some typical values for development are provided; notice that the URLs all reference localhost, but the port numbers have been filled in with default values. Update these as needed to match your environment. -``` +Do the following actions: +1. Refer to the required arguments below +2. Fill in the appropriate values for each of the +3. Prepare the arguments by reformatting them onto a single line + - Ex. `--arg-1 arg1Val --arg-2 arg2Val` +4. Edit the "Server" _run configuration_ +5. Save & apply the changes + +#### Required Program Arguments + +> [!CAUTION] +> **Windows** users cannot simply use these arguments like users of other platforms can.\ +> See [Windows Setup Instructions](./windows.md#setup) for more details. + +```shell --db-user --db-pass --db-host localhost @@ -87,15 +102,32 @@ been filled in with default values. Update these as needed to match your environ --db-name autograder --frontend-url http://localhost:5173 --cas-callback-url http://localhost:8080/auth/callback + +# Use one of the following, but not both --canvas-token +--use-canvas false ``` -While you can use any root user credentials to access the MySQL database, you may be interested in creating -a special login for this project. That decision is left to you. If you do create a different user, however, it will -need nearly root-level permissions in any case (enough to be able to create a new database, then create a "student" -user and `GRANT ALL` privileges to them for that database). The exact requirements are not listed here. +### 6. Run the Autograder Locally -### Canvas Integration +Do the following steps: +1. Run your "Server" run configuration +2. Run the frontend with the following shell commands + +> [!NOTE] +> **Windows** In the case you are running on the Autograder inside a dev container,\ +> you may need to add the `--host` option at the end of the `yarn dev` command (`yarn dev --host`). + +```bash +cd src/main/resources/frontend +yarn dev +``` + +### 7. (Optional) Setup Canvas Integration + +> [!TIP] +> This is only required if you hope to transfer data to Canvas during your workflow;\ +> otherwise, use the `--use-canvas false` program argument and skip this step. To link the autograder with Canvas, you will need to generate a Canvas API key and set the autograder to the current Course and Assignment ID numbers on Canvas. @@ -115,7 +147,8 @@ To generate a Canvas API key: 4. Click "+ New Access Token" 5. Provide the requested information in the modal box 6. Copy the generated access token -7. Use it as the value of the `--canvas-token` program argument above +7. Add the token along side your other program arguments from [step #5](#required-program-arguments) + - Add the argument `--canvas-token ` #### Canvas Data @@ -124,7 +157,7 @@ To update Canvas course ID: 2. The URL should change to something like `https://byu.instructure.com/courses/` 3. Extract `` from the url - This is the number that needs to end up in the configuration table -4. You can set this by logging into the autograder and using the `Update Manually` button in the `Config` tab. +4. You can set this by logging into the autograder and using the `Update Manually` button in the `Config` tab 1. Click that button and modify the `Course Number` input 2. Click `Submit` @@ -134,25 +167,31 @@ To ensure that the assignment IDs and rubric IDs/points are synced with Canvas: 3. Select `Yes` > [!NOTE] -> If there's an issue with the process, you may need to explore updating the course IDs manually. +> If there's an issue with the process, you may need to explore updating the course IDs manually.\ > This can be done directly though the database's `configuration` table or > by clicking `Update Manually` in the `config` tab. Additionally, if you want (not required), you can insert values into the `configuration` table manually (although the step above should do it automatically). See [Insert `config` SQL Statements](db-insert-statements/insert-config-database.md). -### Environment Variables +### 8. (Optional) Environment Variables + +> [!TIP] +> This is only required when running `Loki` locally;\ +> otherwise, simply skip this step. If you are running Loki locally (not required), then you must set the `LOKI_URL` environment variable. The value can be either `localhost:3100` (if you are NOT using docker to develop the app) or `loki:3100` (if you are using docker to develop the app). -### Loading the Configuration Related Tables +### 9. Loading the Configuration Related Tables > [!IMPORTANT] > If you had the autograder prior to 'SUMMER 2024', there is a separate "update" set of SQL commands to use.\ > See [Update `rubric_config` SQL Statements](db-insert-statements/update-rubric-database.md). +This is required. + As of right now, you will need to manually insert the correct values into the `rubric_config` table before being able to run the actual grading on the autograder. See [Insert `rubric_config` SQL Statements](db-insert-statements/insert-rubric-database.md). From c644f915c44041420120f1051dc3189dcc206a74 Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Thu, 31 Oct 2024 10:37:15 -0600 Subject: [PATCH 24/27] Update getting-started.md Generalize to shell code blocks instead of specifically bash --- getting-started/getting-started.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/getting-started/getting-started.md b/getting-started/getting-started.md index 0c4254c2b..3276d8a1b 100644 --- a/getting-started/getting-started.md +++ b/getting-started/getting-started.md @@ -14,7 +14,7 @@ The frontend is built using Vue.js. To run the frontend, you will need to have ` [installing yarn](https://yarnpkg.com/getting-started/install)). After installing `Node` if necessary, run the following to enable `yarn` globally (sudo may be required): -```bash +```shell corepack enable ``` @@ -23,7 +23,7 @@ corepack enable You can run the database either locally with your own MySQL server or inside a Docker container. To run the database inside its own Docker container, run the following in the root of the project: -```bash +```shell docker compose up db -d ``` @@ -61,10 +61,10 @@ Go fish🐟 Specific instructions to update are not included here. > Windows-based shells, even POSIX ones, won't install the correct files. Use `yarn` to install all dependencies. This must be done from the _front end_ root folder. - ```bash - cd src/main/resources/frontend - yarn - ``` +```shell +cd src/main/resources/frontend +yarn +``` ### 4. Setup "Server" _Run Configuration_ @@ -118,7 +118,7 @@ Do the following steps: > **Windows** In the case you are running on the Autograder inside a dev container,\ > you may need to add the `--host` option at the end of the `yarn dev` command (`yarn dev --host`). -```bash +```shell cd src/main/resources/frontend yarn dev ``` From 7423999bd5a5026c531d538260f1fb936479d51e Mon Sep 17 00:00:00 2001 From: James Finlinson Date: Mon, 4 Nov 2024 20:03:27 -0700 Subject: [PATCH 25/27] Move getting-starting inside docs/ --- README.md | 2 +- .../db-insert-statements/insert-config-database.md | 0 .../db-insert-statements/insert-rubric-database.md | 0 .../db-insert-statements/update-rubric-database.md | 0 {getting-started => docs/getting-started}/getting-started.md | 0 {getting-started => docs/getting-started}/windows.md | 0 6 files changed, 1 insertion(+), 1 deletion(-) rename {getting-started => docs/getting-started}/db-insert-statements/insert-config-database.md (100%) rename {getting-started => docs/getting-started}/db-insert-statements/insert-rubric-database.md (100%) rename {getting-started => docs/getting-started}/db-insert-statements/update-rubric-database.md (100%) rename {getting-started => docs/getting-started}/getting-started.md (100%) rename {getting-started => docs/getting-started}/windows.md (100%) diff --git a/README.md b/README.md index ecfef17ab..cc47fecc6 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ docker compose up -d ## Development -New to autograder development? Follow the [Getting Started guide](getting-started/getting-started.md)! +New to autograder development? Follow the [Getting Started guide](docs/getting-started/getting-started.md)! ### How to Contribute diff --git a/getting-started/db-insert-statements/insert-config-database.md b/docs/getting-started/db-insert-statements/insert-config-database.md similarity index 100% rename from getting-started/db-insert-statements/insert-config-database.md rename to docs/getting-started/db-insert-statements/insert-config-database.md diff --git a/getting-started/db-insert-statements/insert-rubric-database.md b/docs/getting-started/db-insert-statements/insert-rubric-database.md similarity index 100% rename from getting-started/db-insert-statements/insert-rubric-database.md rename to docs/getting-started/db-insert-statements/insert-rubric-database.md diff --git a/getting-started/db-insert-statements/update-rubric-database.md b/docs/getting-started/db-insert-statements/update-rubric-database.md similarity index 100% rename from getting-started/db-insert-statements/update-rubric-database.md rename to docs/getting-started/db-insert-statements/update-rubric-database.md diff --git a/getting-started/getting-started.md b/docs/getting-started/getting-started.md similarity index 100% rename from getting-started/getting-started.md rename to docs/getting-started/getting-started.md diff --git a/getting-started/windows.md b/docs/getting-started/windows.md similarity index 100% rename from getting-started/windows.md rename to docs/getting-started/windows.md From af420c131275ab3b736ea479be78b652140aceaf Mon Sep 17 00:00:00 2001 From: DallinFromEarth <112426674+DallinFromEarth@users.noreply.github.com> Date: Tue, 5 Nov 2024 09:55:41 -0700 Subject: [PATCH 26/27] move development and contributing to top --- README.md | 26 +++++++------------------- 1 file changed, 7 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index cc47fecc6..2c86b6da4 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,13 @@ Autograder for [BYU CS 240 Chess project](https://github.com/softwareconstruction240/softwareconstruction/blob/main/chess/chess.md#readme) +## Development and Contributing + +This project relies on TAs like you to maintain and adapt the program! Come join the team! +Check out the [Contribution Guide](docs/CONTRIBUTING.md) to learn how to effectively contribute as a part of the Autograder Development Team! + +Read the [Getting Started Guide](docs/getting-started/getting-started.md) to get the project set up on your machine for development. + ## Important folders ``` @@ -44,22 +51,3 @@ docker compose up -d > [!NOTE] > If you are using the docker MySQL database, ensure that in > `src/main/resources/db.properties` the property `db.url` is set to `db:3306`. - -## Development - -New to autograder development? Follow the [Getting Started guide](docs/getting-started/getting-started.md)! - -### How to Contribute - -Here are a few tips for first projects or tasks to learn the autograder: -- Review the Sequence/Class Diagrams (_coming soon_) and try creating one -- Add documentation -- Find a section of under-tested code and add some unit tests -- Take a look through the GitHub repo's [Issues](https://github.com/softwareconstruction240/autograder/issues) page -and find one you like, especially (but not limited to) ones labeled -["good first issue"](https://github.com/softwareconstruction240/autograder/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). - -It's also a good idea to read through the repo's -`CONTRIBUTING.md` ([COMING SOON](https://github.com/softwareconstruction240/autograder/issues/448)). - -Don't be afraid to submit a PR, and most importantly, just get sucked in! From 6e7831d1eb925cd356b2179d52bc5d5be3bf9c0a Mon Sep 17 00:00:00 2001 From: DallinFromEarth <112426674+DallinFromEarth@users.noreply.github.com> Date: Tue, 5 Nov 2024 10:06:31 -0700 Subject: [PATCH 27/27] point contributing link to issue temporarily --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2c86b6da4..7dc59b276 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Autograder for [BYU CS 240 Chess project](https://github.com/softwareconstructio ## Development and Contributing This project relies on TAs like you to maintain and adapt the program! Come join the team! -Check out the [Contribution Guide](docs/CONTRIBUTING.md) to learn how to effectively contribute as a part of the Autograder Development Team! +Check out the [Contribution Guide](https://github.com/orgs/softwareconstruction240/projects/1/views/1?pane=issue&itemId=84732654&issue=softwareconstruction240%7Cautograder%7C448) to learn how to effectively contribute as a part of the Autograder Development Team! Read the [Getting Started Guide](docs/getting-started/getting-started.md) to get the project set up on your machine for development.