docs: add base README
This commit is contained in:
@@ -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
|
||||
<settings>
|
||||
<mirrors>
|
||||
<mirror>
|
||||
<id>devneeds-maven</id>
|
||||
<name>DevNeeds Maven Mirror</name>
|
||||
<url>https://maven.devneeds.ir/</url>
|
||||
<mirrorOf>central</mirrorOf>
|
||||
</mirror>
|
||||
<mirror>
|
||||
<id>local-maven-mirror</id>
|
||||
<name>Local Maven Mirror</name>
|
||||
<url>https://mirror-maven.runflare.com/maven2</url>
|
||||
<mirrorOf>central</mirrorOf>
|
||||
</mirror>
|
||||
</mirrors>
|
||||
</settings>
|
||||
```
|
||||
|
||||
**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!
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user