# SSPfR Section 1 Homework

## Preliminary Instructions
This homework will be automatically graded using GitHub Actions. Therefore, **modifying any file within the `.github` directory in any form is strictly prohibited**. Any violation will result in a score of 0 for this assignment.

All other files can be freely modified. However, if any issues arise after modifications, you must revert to a previous version on your own.

All the grading is done on the main branch.

Assignment video link: [Youtube](https://youtu.be/xfH8r_WUyDI)

**Deadline: 2025/3/11 23:59**

## Assignment Map & Grading Criteria

| Component | Weight | Component | Weight |
| ---------------------------- | ------ | ------------------------------ | ------ |
| Git Assignment | 8% | Commit Message Assignment | 3% |
| Docker Assignment | 8% | DarkMaze Docker | 15% |
| Clean Code Assignment | 8% | DarkMaze Tools | 24% |
| Tools Assignment | 8% | DarkMaze Unit Test | 18% |
| Unit Test Assignment | 8% | | |

---

### Evaluation Process

1. **Section 1 – Core Assignments (40% Total):**
- **Git Assignment**
- **Docker Assignment**
- **Clean Code Assignment**
- **Tools Assignment**
- **Unit Test Assignment**

These must be completed first. Only after finishing all items in Section 1 will the evaluation process open up for Section 2.

2. **Section 2 – DarkMaze Project (57% Total):**
- **DarkMaze Docker**
- **DarkMaze Tools**
- **DarkMaze Unit Test**

3. **Independent Evaluation (3% Total):**
- **Commit Message:** This component is evaluated separately from the two sections and carries a weight of 3%.


---

The grading process is sequential: complete Section 1 before proceeding to Section 2, and remember that the Commit Message score is independent and does not fall under any specific section.

## Prerequisite Steps - Retrieving Repositories
Click the link: [https://classroom.github.com/a/L6abwohU](https://classroom.github.com/a/L6abwohU)

You will be directed to the following screen:

Select your student ID and proceed.

Click "Agree" and continue.

Once done, your assignment repository will be created. The link in the blue section is your repository. It functions like a regular repository, so it is not demonstrated here—please access it yourself.

## Homework Assignments

### 1. Commit Message Assignment (3%)

- **Assignment video timestamp:** [2:32](https://youtu.be/xfH8r_WUyDI?feature=shared&t=152)

- **Objective:**
Ensure that your commit messages comply with the specified rules as outlined in the provided article.

- **Instructions & Steps:**
- Read the article on commit message guidelines: [Commit Message Guidelines](https://ithelp.ithome.com.tw/articles/10228738).
- Ensure that at least 90% of your pushed commits follow these rules.
- Remember: only your latest pushed commits will be evaluated—if you make a mistake, correct it in your next push.

- **Submission Requirements:**
Push your commits to the repository with compliant commit messages.

- **Additional Notes:**
This assignment is worth 3% of your total grade.

---

### 2. Git Assignment (8%)

- **Assignment video timestamp:** [3:38](https://youtu.be/xfH8r_WUyDI?feature=shared&t=218)

- **Objective:**
Practice using Git and GitHub by forking a repository, creating a new file, and making a commit with a proper commit message.

- **Instructions & Steps:**
1. **Account Setup:**
- Create an account on Git and GitHub (if you haven’t done so already).
2. **Repository Forking:**
- Fork the given repository on GitHub. (This step has already been completed in "Prerequisite Steps - Retrieving Repositories.")
3. **File Creation:**
- In the `GitHW` directory, create a new file named `studentID.md`.
- Add the text:

       Hello World your_student_ID

4. **Commit Changes:**
- Add and commit the new file with the commit message:

       feat: gitHW commit

5. **Push Changes:**
- Push the file to your repository.

- **Submission Requirements:**
Push your commits to GitHub ensuring the commit message follows the guidelines.

---

### 3. Docker Assignment (8%)

- **Assignment video timestamp:** [4:18](https://youtu.be/xfH8r_WUyDI?feature=shared&t=258)

- **Objective:**
Run the webpage `on port 5000` from the `DockerHW` directory using Docker Compose.

- **Instructions & Steps:**
1. **Dockerfile Creation:**
- Write a complete `Dockerfile` that builds the image for the webpage.
2. **Docker Compose Setup:**
- Create a `docker-compose.yml` file to define and run the container.
3. **Local Verification:**
- Run `docker-compose up` in the `DockerHW` directory to verify that the container is created successfully.

- **Submission Requirements:**
Once the container runs locally, push both the `Dockerfile` and `docker-compose.yml` to your repository. CI testing will verify their correctness.

---

### 4. Clean Code Assignment (8%)

- **Assignment video timestamp:** [5:14](https://youtu.be/xfH8r_WUyDI?feature=shared&t=314)

- **Objective:**
Refactor the code in `CleanCodeHW/calculate_pi.py` to eliminate magic numbers and replace unreasonable variable names.

- **Instructions & Steps:**
1. **Identify Magic Numbers:**
- Search the file for hard-coded numerical values (magic numbers) and replace them with appropriately named variables.
2. **Rename Variables:**
- Identify any variable names that do not clearly describe their purpose and rename them to more meaningful names.
3. **Maintain Whitespace:**
- **Important:** Do not add or remove any whitespace to avoid causing errors.

- **Submission Requirements:**
Commit and push the modified `calculate_pi.py` file to your repository.

---

### 5. Clean Code Tools Assignment (8%)

- **Assignment video timestamp:** [5:55](https://youtu.be/xfH8r_WUyDI?feature=shared&t=355)

- **Objective:**
Refactor the code in `ToolsHW/hw.py` following Clean Code principles and integrate SonarQube to assess code quality.

- **Instructions & Steps:**
1. **Refactor `hw.py`:**
- The program should compute `1 * 1` and, if the result is correct, play a video.
- Standardize the code style (follow PEP 8 guidelines).
- Remove unnecessary variables, functions, and duplicate code.
- Simplify conditional structures and ensure function names are meaningful.
2. **Integrate SonarQube for Code Quality Testing:**
- **Deploy SonarQube Locally:**
- Run the command:

         docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community

- Access SonarQube via [http://localhost:9000](http://localhost:9000) and log in using username and password: `admin`.
- **Generate and Run Scanner Command:**
- Follow the manual setup: “Manually -> Set Up -> Locally -> Generate -> Choose Other.”
- Copy the generated command (similar to below) and run it in your project directory:

         sonar-scanner.bat -D"sonar.projectKey=dfs" -D"sonar.sources=." -D"sonar.host.url=http://localhost:9000" -D"sonar.login=your_token"

- Consult the [SonarQube Scanner Documentation](https://docs.sonarsource.com/sonarqube-server/10.8/analyzing-source-code/scanners/sonarscanner/) if needed.
- **Analyze and Improve:**
- Review the SonarQube report for bugs, code smells, and duplicate code.
- Further improve your code based on the report.

- **Grading Criteria:**
- SonarQube Analysis: 4%
- Achieving a grade of A or above: 4%

- **Submission Requirements:**
Commit and push your refactored `hw.py` along with the SonarQube integration setup to your repository.

---

### 6. Unit Test Assignment (8%)

- **Assignment video timestamp:** [6:52](https://youtu.be/xfH8r_WUyDI?feature=shared&t=412)

- **Objective:**
Complete the unit tests for two problems: FizzBuzz and Regular Expression Matching.

- **Instructions & Steps:**
**(a) FizzBuzz Testing**
- **Basic Unit Test (2 points):**
1. Complete the file `test_fizzbuzz.py` located in the `Fizz Buzz/Basic` folder.
2. Run pytest in that folder; the expected result is:

       1 failed, 3 passed in <time>s

- **Class Unit Test (2 points):**
1. Complete the file `test_fizzbuzz.py` in the `Fizz Buzz/Class` folder.
2. Note:
- `test_main` acts as an integration test.
- `test_invalid_input` should correctly handle edge cases by raising an error.
3. Run pytest; the expected result is:

       2 failed, 5 passed in <time>s

**(b) Regular Expression Matching Testing (4 points)**
- **Parametrized Testing:**
1. Use a single function to run all test cases found in `Regular Expression Matching/test_solution`.
2. Run pytest; the expected result is:

       1 failed, 6 passed in <time>s

- **Handling xfail Tests:**
1. Remove the triple quotes surrounding the xfail test.
2. Move the failed test case into a new function.
3. Re-run pytest; the expected outcome is:

       6 passed, 1 xfailed in <time>s

- **Submission Requirements:**
Commit and push all updated test files and any changes made to your repository.

- **Additional Notes:**
There will be more instructions in the UnitTestHW folder on GitHub.
---

### 7. DarkMaze Assignment (57%)

- **Assignment video timestamp:** [8:07](https://youtu.be/xfH8r_WUyDI?feature=shared&t=487)

- **Objective:**
Complete the DarkMaze project, which involves setting up Docker, refactoring code, and creating unit tests for a maze game that challenges you to navigate through darkness with three lives.

- **Instructions & Steps:**
**Running DarkMaze Without Docker:**
1. **Back-End:**
- Navigate to the `DarkMaze/backend` directory.
- Run the command:

       py -m src.main

2. **Front-End:**
- Navigate to the `DarkMaze/frontend` directory.
- Run the command:

       py -m src.main

3. **Play the Game:**
- Open your browser and go to: [http://localhost:8088](http://localhost:8088).

**Assignment Categories and Weights:**
- **DarkMaze Docker (15%):**
- Set up and configure Docker (e.g., writing Dockerfile and docker-compose.yml) for the DarkMaze project.
- **DarkMaze Tools (24%):**
- Refactor and improve the game code following Clean Code principles (similar to previous assignments).
- **DarkMaze Unit Test (18%):**
- Create or complete unit tests to ensure the game functions correctly.

- **Submission Requirements:**
Commit and push the complete DarkMaze project—including all Docker configuration files, refactored code, and test files—to your repository. CI/CD pipelines will run tests based on your submission.

## How to View Your Score
Click to enter the action, select the workflow you want to view, and scroll down to check the `calculate-score summary`.