From 9c8735c728c4da448fe468a19792cc6514ba8d5e Mon Sep 17 00:00:00 2001 From: Mehrdad Shirvani Date: Thu, 16 Apr 2026 18:33:48 +0330 Subject: [PATCH] docs: add base README --- README.md | 281 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9900a37 --- /dev/null +++ b/README.md @@ -0,0 +1,281 @@ +# Second Assignment - Git and Java Basics + +Are you ready to challenge yourself with some algorithmic problems? +Let's kick things off by solving three basic problems to refresh your knowledge of *Java* and *Git*. + +## Getting Started + +Follow these steps to set up your project: + +### 0. Watch the introductory video +We have recorded a special video, explaining the exact steps that needs to be taken to complete this assignment. +Here is the [link]() + +### 1. Fork and Clone the Repository + +First, fork the repository on GitHub or Gitea (click the Fork button on the top-right). + +Then clone your forked repository: + + +``` +git clone https://git.meshcomp.ir/YOUR_USERNAME/repository-name.git +``` +or +``` +git clone https://github.com/YOUR_USERNAME/repository-name.git +``` + + +then +``` +# Navigate into the project directory: +cd repository-name +``` + + +### 2. Share with Your Mentor + +**Add mentor as collaborator:** +1. Go to your forked repository on GitHub or Gitea +2. Click Settings → Collaborators → Add people +3. Enter your mentor's GitHub or Gitea username or email + + +### 3. Set up Mirrors if You Have Restricted Internet Connection + +If you're behind a firewall or have restricted internet access, configure Maven to use mirror repositories. + +**For Windows:** +- Location: `C:\Users\YourUsername\.m2\settings.xml` + +**For macOS/Linux:** +- Location: `~/.m2/settings.xml` (the `.m2` folder is in your home directory) + +**Create the `.m2` folder if it doesn't exist:** +```bash +# Windows (Command Prompt): +mkdir %USERPROFILE%\.m2 + +# macOS/Linux: +mkdir -p ~/.m2 +``` + +**Place this configuration in `settings.xml`:** + +```xml + + + + devneeds-maven + DevNeeds Maven Mirror + https://maven.devneeds.ir/ + central + + + local-maven-mirror + Local Maven Mirror + https://mirror-maven.runflare.com/maven2 + central + + + +``` + +**Reload Maven configuration:** + +Click on the Maven tool window → Click "Reload All Maven Projects" button (circular arrows) + +**If mirrors still don't work:** Contact your mentor with details about your network setup (proxy, firewall, region). They may provide institution-specific mirrors. + +### 4. Unit Tests +- In the test folders there are some unit tests using junit library that you and your mentors will use in order to test the correctness of your program. +- You can run the file or individual functions to see the results of the test in IntelliJ IDEA. + + +### 5. Create a `develop` branch + +```bash +# Create and switch to the develop branch: +git checkout -b develop + +# Verify you're on the develop branch: +git branch +# You should see "* develop" in the output +``` + +### 6. Complete the Tasks + +**Task 1: Implement MainExercises.java** +- Open `src/main/java/MainExercises.java` +- Implement the following methods based on the comments: + +```java +// Example method signature you'll find: +public char[][] generateTriangle(int n); +public int[] spiralTraversal(int[][] values, int rows, int cols); +public int[][] intPartitions(int n); +``` + +**Task 2: Implement BonusExercises.java (Optional)** +- Open `src/main/java/BonusExercises.java` +- Implement bonus methods for extra credit + +**Task 3: Make all tests pass** +- Run the tests frequently as you implement each method +- Each test file under `test/java` should execute without failures + +**Project structure reference:** +``` +src +├── main +│ ├── java +│ │ ├── MainExercises.java # REQUIRED: Implement all methods +│ │ ├── BonusExercises.java # OPTIONAL: Extra credit +│ └── resources +└── test + └── java + ├── MainTests + │ ├── TestPartitions.java # MUST PASS + │ ├── TestTriangle.java # MUST PASS + │ └── TestTraversal.java # MUST PASS + ├── BonusTests + │ ├── TestDates.java # OPTIONAL + │ ├── TestEmail.java # OPTIONAL + │ ├── TestPalindromes.java # OPTIONAL + │ └── TestPasswords.java # OPTIONAL +``` + +### 7. Commit Your Work Locally + +**Stage and commit files:** + +```bash +# Check which files have changed: +git status + +# Stage a specific file: +git add src/main/java/MainExercises.java + +# Stage all changed files at once: +git add . + +# Commit with a descriptive message: +git commit -m "Implement countPartitions method and triangle type checker" + +# Good commit message examples: +# - "Complete all main exercises, all tests passing" +# - "Add bonus email validation with regex" + +# Bad commit messages (avoid these): +# - "Update" +# - "Fix stuff" +# - "WIP" +``` + +**View commit history:** +```bash +git log --oneline # Shows compact commit history +``` + + +## 8. Push to Remote Repository + +```bash +# First, ensure you're on the develop branch: +git branch # Should show "* develop" + +# Push to remote (note: branch name must match exactly - all lowercase): +git push origin develop + +# If this is your first push to develop branch, you might see: +# git push --set-upstream origin develop +# Just use the command Git suggests +``` + +## 9. Create a Pull Request to YOUR Own Repository + +**Important:** Create the pull request in your OWN forked repository (not the original/main classroom repository). + +### Step-by-Step Pull Request Process: + +**Step 1: Navigate to your forked repository on GitHub or Gitea** +``` +https://git.meshcomp.ir/YOUR_USERNAME/repository-name +``` +or +``` +https://github.com/YOUR_USERNAME/repository-name +``` + +**Step 2: Create a new pull request** +- Click on **"Pull requests"** tab (top navigation) +- Click the green **"New pull request"** button + +**Step 3: Configure the pull request branches** +``` +base: main ←── compare: develop +(your main branch) (your develop branch) +``` + +**Important settings:** +- **base repository:** `YOUR_USERNAME/repository-name` (your fork) +- **base branch:** `main` (or `master` depending on your repo) +- **head repository:** `YOUR_USERNAME/repository-name` (same fork) +- **compare branch:** `develop` + +**Step 4: Create the pull request** +- Click **"Create pull request"** button +- Add a title: `"Complete assignment - ready for grading"` +- Add a description: +```markdown +## Assignment Submission + +### Completed Tasks: +- [x] All MainExercises implemented +- [x] All unit tests passing +- [x] Code follows Java conventions + +Ready for review and grading! +``` + +**Step 5: Final submission** +- Click **"Create pull request"** (green button) +- Share the pull request link with your mentor + +## 10. Mentor Reviews and Grades Your Project + +### What your mentor will do: + +1. **Review the pull request** in your repository +2. **Run the unit tests** to verify your solutions +3. **Check code quality** (naming conventions, comments, efficiency) +4. **Merge the pull request** if everything is correct: +- Click **"Merge pull request"** button +- Confirm with **"Confirm merge"** + + +## Prerequisites + +Before starting, ensure you have: + +- **Basic knowledge of Java** (variables, loops, conditionals, arrays, methods) +- **A good grasp of Git commands** (clone, add, commit, push, branch) + +## Getting Help + +- **Mentor contact:** Available during office hours and via [specify platform] +- **Git documentation:** https://docs.meshcomp.ir/git + +--- + +Good luck, and happy coding! + + + + + + + + +