Merge branch 'master' into feat/game-store-create-retrieve

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Description
+[Provide a brief description of the changes made in this pull request.]
+
+## Motivation and Context
+[Explain the motivation behind these changes and provide any relevant context.]
+
+## How to Test
+[Describe the steps to test the changes made in this pull request.]
+
+## Related Issues
+[If applicable, mention any related issues or pull requests.]
+
+## Checklist
+- [ ] I have tested these changes locally.
+- [ ] I have reviewed the code and ensured it follows the project's coding guidelines.
+- [ ] I have updated the documentation, if necessary.
+- [ ] I have assigned reviewers to this pull request.
+
+## Screenshots (if applicable)
+[If your changes include any visual updates, provide screenshots here.]

.github/issue_template.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]

CONTRIBUTING.md

@@ -1,4 +1,3 @@
-
 ---
 
 # Contributing to Multiplayer UNO Game
@@ -21,6 +20,8 @@ Maintainers will approve the issue and add relevant labels to indicate that its
 
 ### Fixing Issues
 
+Given that you have already forked the repository and set it up locally:
+
 1. **Find an Issue to Work On**:
    - Look for issues labeled `help wanted` or `good first issue` if you are a first-time contributor.
 
@@ -29,22 +30,13 @@ Maintainers will approve the issue and add relevant labels to indicate that its
 
    If you are not able to make progress on an issue in 4 days, you will be unassigned from the issue and it will be available for others to work on.
 
-3. **Fork the Repository**:
-   - Fork the repository to your own GitHub account by clicking the "Fork" button on the top right of the repository page.
-
-4. **Clone Your Fork**:
-   - Clone your fork to your local machine:
-
-     ```bash
-     git clone https://github.com/yourusername/multiplayer-uno.git
-     cd multiplayer-uno
-     ```
-
 5. **Create a Branch**:
    - Create a new branch for your fix from the `main` branch. Use a descriptive name for your branch:
+   It is crucial to fetch from upstream before creating a branch. This ensures that your branch is created from the latest changes in the main branch.
 
      ```bash
-     git checkout -b fix/issue-#123
+     git fetch upstream
+     git checkout -b <your branch name> upstream/main
      ```
 
 6. **Implement Your Fix**:
@@ -54,7 +46,7 @@ Maintainers will approve the issue and add relevant labels to indicate that its
    - Thoroughly test your changes to ensure they work as intended and do not introduce any new bugs.
 
 8. **Commit Your Changes**:
-   - Please refer to the commit message guidelines in [CONVENTIONS.md](CONVENTIONS.md) for writing meaningful commit messages.
+   - Please refer to the commit message guidelines in [CONVENTIONS.md](CONVENTIONS.md#commit-message-guidelines) for writing meaningful commit messages.
 
 9. **Push Your Changes**:
    - Push your branch to your forked repository:
@@ -64,10 +56,10 @@ Maintainers will approve the issue and add relevant labels to indicate that its
      ```
 
 10. **Open a Pull Request**:
-    - Open a pull request (PR) against the `main` branch of the original repository. Provide a clear description of your changes and reference the issue number you are fixing. Fill the self review checklist.
+    - Open a pull request (PR) against the `main` branch of the original repository. Provide a clear description of your changes and reference the issue number you are fixing. Fill the self review checklist. You should only solve one issue in one PR.
 
 11. **Address Review Comments**:
-      - If maintainers suggests changes to your code, make the necessary updates and push the changes to your branch. The fix/changes should not be in a separate commit - rather the original commit must be modified force-pushed to the branch. If merge conflicts arise, use `git rebase` to resolve them. 
+      - If maintainers suggests changes to your code, make the necessary updates and push the changes to your branch. The fix/changes should not be in a separate commit - rather the original commit must be modified force-pushed to the branch. If merge conflicts arise, use `git rebase` to resolve them. See the section on [editing commit history](#editing-commit-history) for more details.
 
 <!-- todo: add details about modifying pull requests following a review.-->
 
@@ -78,6 +70,85 @@ Maintainers will approve the issue and add relevant labels to indicate that its
 - Addressing reviews on existing PRs is as important as creating new PRs. Please be responsive to the feedback and make the necessary updates.
 - Create a new branch for each issue you are working on. This will help you keep your changes isolated and make it easier to manage multiple PRs. The branch should be created from upstream/master, and only after fetching the latest changes from the main branch from upstream first.
 
+## Common Git Operations you may need to perform
+
+During contribution, you will often need to rewrite commit history or sync your branch with the main branch. 
+Here is how you should do it:
+
+### Syncing your branch with the main branch
+If there have been updates to the upstream/master branch after you created your branch, you should sync your branch with the main branch. This will help you avoid merge conflicts and keep your branch up-to-date.
+
+```bash
+git fetch upstream
+git rebase upstream/main
+```
+Rebasing your branch on top of the main branch will apply your changes on top of the latest changes in the main branch.
+It would be equivalent to merging the main branch into your branch, but it keeps the commit history clean. The commit history will reflect that your changes were made on top of the latest changes in the main branch.
+
+If any merge conflicts occur, you will need to resolve them manually. Code editors (like VSCode) have built-in tools to help you resolve merge conflicts. After resolving the conflicts, you can continue the rebase process by running `git rebase --continue`. 
+
+Now the local copy of the branch is synced with upstream/main. You need to force push these changes to origin, since the commit history has been rewritten.
+
+```bash
+git push --force
+```
+
+### Editing commit history
+A maintainer might ask you to edit your commit history, for example, change the variable name, add/remove lines, change commit message, drop commits etc. The changes should not be made as a separate commit, rather you should edit the original commit with the changes. You can do this using an interactive rebase.
+
+Lets take the case where I want to merge 4 commits through a PR. The maintainer has asked me to change some variable names I had made through the 2nd commit. I am also asked to rename the commit message of the 3rd commit. 
+
+```bash
+git rebase -i HEAD~4
+```
+
+The `-i` represents interactive mode, i.e, after each commit, git will pause and ask you what you want to do with the commit. `HEAD~4` means that I want to rebase the last 4 commits.
+
+After running the command, you will see a list of commits in your default text editor. It will look something like this:
+
+```bash
+
+pick 1a2b3c4d This is the commit message of Commit 1
+pick 5e6f7g8h Added variables in index.js.
+pick 9i0j1k2l Updeted README.md
+pick 3m4n5o6p Commit msg 4
+
+```
+To drop a commit, you can simply delete the line corresponding to that commit. To edit a commit, you can replace `pick` with `edit` in front of the commit you want to edit.
+
+Since we wish to edit the 2nd and 3rd commit, we will change the file to look like this:
+
+```bash
+
+pick 1a2b3c4d This is the commit message of Commit 1
+edit 5e6f7g8h Added variables in index.js.
+edit 9i0j1k2l Updeted README.md
+pick 3m4n5o6p Commit msg 4
+
+```
+Save the changes and exit.
+
+After saving the changes, git will then apply the 2nd commit and pause. You can now make the necessary changes to the code, and then stage the changes (Using `git add .`). You then incorporate the changes to the 2nd commit using `git commit --amend`. The editor opens, asking for commit meessage. You can change the commit message if needed at this needed.
+
+
+#### "Uncommitting" a commit
+When you choose to edit the 2nd commit, git pauses **after** applying the second commit. You might wish to uncommit all the changes made in the 2nd commit. In that case, you run `git reset HEAD~1`. This will uncommit the changes made in the 2nd commit, but keep the changes in the working directory. You can then make the necessary changes and commit them again. The `git reset` command can be used to uncommit any number of commits. For example, `git reset HEAD~2` will uncommit the last 2 commits. Note that after doing this operation, there would be no way to distinguish the changes made in the two commits. This command can be used outside of an interactive rebase as well.
+
+After making the changes, you can continue the rebase process by running `git rebase --continue`. Git will then apply the 3rd commit and pause again. You can then change the commit message using `git commit --amend`. After making the changes, you can continue the rebase process by running `git rebase --continue`.
+
+When there are no more commits left, the rebase process will be complete.
+
+After all the commits have been applied, you can push the changes to your branch using `git push --force`. This will overwrite the commits in the remote branch in your forked repository with the changes you just made locally.
+
+#### Tip
+VSCode provides a helpful UI to perform these operations. You can set the default text editor for Git to VSCode by running the following command:
+
+```bash
+git config --global core.editor "code --wait"
+```
+This will open VSCode whenever you run a command that requires a text editor, like `git rebase -i HEAD~4`, `git commit --amend`, etc.
+
+
 ## Code Review
 
 All contributions go through a code review process to ensure the quality and maintainability of the codebase. During the review, maintainers may provide feedback or request changes to your code. Please be responsive to the feedback and make the necessary updates. There may be multiple rounds of review before your changes are approved.
@@ -94,4 +165,6 @@ If you have any questions about the project or how to contribute, feel free to r
 
 Do not worry about the points scored during contributing. Feel free to make mistakes, but be open to acknowledge and fix them. The main goal is to learn and grow together. Depending on your enthusiasm, dedication and contribution, you will be judged in the end of CSOC.
 
+The main purpose for this whole activity is to get you acquainted with the open source contribution workflow. We cannot replicate the exact workflow of a real open source project due to the time constraints, but we have tried to cover the most important aspects of it (related to git, code review, etc.).
+
 ---

CONVENTIONS.md

@@ -20,6 +20,7 @@
 - Use meaningful commit messages that describe the changes made in the commit.
 - Please do only one thing in a single commit. If you are fixing a bug and refactoring some code, make two separate commits.
 - If you make tweaks to existing code to fit your implementation, do it in a separate commit.
+- Your commits would be more readable if each line is limited to around 72 characters. Break long lines into multiple lines if necessary.
 - Commit messages should be of the format:
     ```
     <area_of_code>: <short_description>
@@ -33,14 +34,15 @@
     server: Add endpoint to fetch user data.
 
     This commit adds a new endpoint to the server that allows clients to fetch user data.
+    We fetch the user data from MongoDB and return it as a JSON response, filtering out sensitive information.
 
-    Fixes #28686
+    Fixes #28626
     ```
 
     ```
     client: Refactor user profile component.
 
-    This commit refactors the user profile component to improve code readability and maintainability.
+    This commit refactors the user profile component to improve code readability and maintainability. 
 
     ```
 
@@ -50,5 +52,6 @@
 - Use proper spacing and line breaks to improve code readability.
 - Avoid unnecessary code duplication and strive for code reusability.
 - Write clear and concise documentation for public APIs and important functions. Do not over-document trivial functions.
+- We decided not to use typescript in the backend to accomodate more contributors, but we do use JSDocs for documentation. Please document your code using JSDocs.
 
 Remember to review and adhere to these conventions to maintain a clean and consistent codebase.

INSTALLATION.md

@@ -75,14 +75,14 @@ cd multiplayer-uno
 4. Start the frontend development server:
 
     ```bash
-    npm start
+    npm run dev
     ```
 
-   The frontend application should now be running on `http://localhost:3000`.
+   The frontend application should now be running on `http://localhost:5173`.
 
 ## Running the Application
 
-With both the backend and frontend servers running, open your browser and navigate to `http://localhost:3000` to access the UNO game. You should be able to sign up, log in, create or join game rooms, and start playing.
+With both the backend and frontend servers running, open your browser and navigate to `http://localhost:5173` to access the UNO game. You should be able to sign up, log in, create or join game rooms, and start playing.
 
 ## Troubleshooting
 
@@ -91,7 +91,7 @@ If you encounter any issues during installation, consider the following steps:
 - **Check Dependencies**: Ensure that all dependencies are installed correctly by running `npm install` in both the `backend` and `frontend` directories.
 - **Environment Variables**: Ensure that your `.env` file contains the correct values for your MongoDB connection string and JWT secret.
 - **Server Logs**: Check the terminal output for any error messages from the backend or frontend servers.
-- **Port Conflicts**: Make sure that ports `5000` (backend) and `3000` (frontend) are not being used by other applications.
+- **Port Conflicts**: Make sure that ports `5000` (backend) and `5173` (frontend) are not being used by other applications.
 
 ## Contact
 

backend/controllers/gameControllers.js

@@ -1,2 +1 @@
 // Implement the handler for `/events` endpoint. Refer to ARCHITECTURE.md for implementation details.
-

backend/eslint.config.js

@@ -0,0 +1,14 @@
+import jsdoc from 'eslint-plugin-jsdoc';
+
+export default [
+    {
+        files: ['**/*.js'],
+        plugins: {
+            jsdoc: jsdoc,
+        },
+        rules: {
+            'jsdoc/require-description': 'error',
+            'jsdoc/check-values': 'error',
+        },
+    },
+];

backend/gameStore.js

@@ -16,8 +16,14 @@ export function createGame() {
 }
 
 /**
+<<<<<<< feat/game-store-create-retrieve
  * Retrieve a game from the games map
  * @param {string} id gameId
+=======
+ *  Retrieves a game from the store using its id.
+ *
+ * @param {string} id Game id
+>>>>>>> master
  * @returns {GameEngine|null} GameEngine instance
  */
 export function retrieveGame(id) {