Skip to content

Fixes #1069 Added "Testing Your Changes" Section in CONTRIBUTING.md #1070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Shobhini wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Fixes #1069 Added "Testing Your Changes" Section in CONTRIBUTING.md #1070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5410b6
#1069 Update CONTRIBUTING.md: Enhance testing guidelines and reorderi…
Shobhini Mar 22, 2026
b2b3bed
Update README.md: Enhance prerequisites section with installation ver…
Shobhini Mar 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 57 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,16 @@ This project is in its early stage — so **you’re welcome to help build it fr
```bash
git checkout -b my-feature
```
4. **Start coding!** Edit files, add features, fix bugs.
5. **Commit and push**
4. **Set up your development environment** (see [README.md](README.md#-getting-started-development))
5. **Start coding!** Edit files, add features, fix bugs.
6. **Test your changes** (see section below)
7. **Commit and push**

```bash
git commit -m "Add: my feature"
git push origin my-feature
```
6. **Open a Pull Request** on the main repository. Your PR must target the `master` branch!
8. **Open a Pull Request** on the main repository. Your PR must target the `master` branch!

---

Expand All @@ -48,6 +50,58 @@ We’ll also add `good first issue` and `help wanted` labels as the project evol

---

### 🧪 Testing Your Changes

Before submitting a pull request, make sure to test your changes locally:

#### 1. Frontend Testing

**Run the development server:**
```bash
npm run dev
```
- Manually test your feature in the browser at `http://localhost:5173`
- Check that your changes work across different screen sizes (responsive design)
- Open DevTools (F12) and check for console errors or warnings

**Run linting and formatting checks:**
```bash
npm run lint # Check code quality
npm run lint:fix # Automatically fix issues
npm run format:check # Check if files are formatted correctly
npm run format # Format all files
```

**Build for production (optional but recommended):**
```bash
npm run build
npm run preview # Preview the production build
```

#### 2. Backend Testing

**Make sure the backend is running:**
```bash
cd backup_existing_project/backend
source venv/bin/activate # or venv\Scripts\activate on Windows
python3 run.py
```

**Test your API changes:**
- Use tools like [Postman](https://www.postman.com/) or [curl](https://curl.se/) to test API endpoints
- Check that error handling works correctly
- Test with invalid inputs to ensure proper validation

#### 3. Before Committing

- Ensure no console errors in browser DevTools
- Ensure linting passes (`npm run lint` shows no errors)
- Ensure formatting is correct (`npm run format:check` passes)
- Test on both desktop and mobile browsers if possible
- Write clear, descriptive commit messages

---

### 📚 Guidelines

* Keep code clean and readable
Expand Down
51 changes: 46 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,16 @@ notesvault/

### Prerequisites

- **Node.js 20+** (for frontend)
- **Python 3.x** (for backend)
- **npm 10+**
- **Node.js 20+** (for frontend) - [Download](https://nodejs.org/)
- **Python 3.8+** (for backend) - [Download](https://www.python.org/)
- **npm 10+** (usually comes with Node.js)

#### Verify installations:
```bash
node --version
npm --version
python3 --version
```
Comment on lines +86 to +90
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Resolve MD046 warnings on newly added code blocks.

These fenced blocks are currently flagged by markdownlint (MD046) at Line 86, Line 113, Line 120, and Line 137. Please align these blocks with the repo’s configured code-block style so docs lint stays clean.

Also applies to: 113-113, 120-120, 137-137

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 86-86: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 86 - 90, The fenced code blocks in README containing
the commands "node --version", "npm --version", "python3 --version" (and the
other two blocks flagged) don’t match the repo’s configured fenced-code style
and trigger MD046; update those fenced blocks to the repository’s canonical
style (use the preferred fence marker and language tag, e.g. ```sh or the
configured token), ensure a blank line before and after each fence if required
by the linter, and make the same consistent change for the other flagged blocks
so all README code fences (including the ones showing node/npm/python commands)
conform to the repo rule.


### 1. Clone the repository

Expand All @@ -100,11 +107,19 @@ The frontend will run at `http://localhost:5173`

### 3. Set up Backend (Flask)

**Terminal 2:**
**Terminal 2 (new terminal window):**

First, set up Python virtual environment:
```bash
cd backup_existing_project/backend
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```

Then install dependencies and run:
```bash
pip install -r requirements.txt
python run.py
python3 run.py
```

The backend API will run at `http://localhost:5000`
Expand All @@ -116,6 +131,32 @@ The backend API will run at `http://localhost:5000`

The frontend is configured to proxy API requests to the backend automatically.

### Troubleshooting

**Backend won't start - "Port 5000 in use"**
```bash
# Check what's using port 5000
lsof -i :5000

# Kill the process (replace PID)
kill -9 <PID>

# Or start on a different port
python3 run.py --port 5001
```
Comment on lines +145 to +146
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify whether backend run.py accepts/handles a --port argument.
# Expected:
# - If argparse/click/sys.argv handling exists for port, command is likely valid.
# - Otherwise, docs should be updated to the supported way (e.g., env var or app.run(port=...)).

set -euo pipefail

RUNPY_PATH="$(fd -t f 'run.py' | rg 'backup_existing_project/backend/run.py' || true)"
if [ -z "$RUNPY_PATH" ]; then
  echo "run.py not found at expected location"
  exit 0
fi

echo "Inspecting: $RUNPY_PATH"
nl -ba "$RUNPY_PATH" | sed -n '1,260p'

echo
echo "Searching for explicit CLI parsing related to port..."
rg -n -C2 'argparse|click|sys\.argv|--port|port\s*=|app\.run\(' "$RUNPY_PATH"

Repository: opensource-society/notesvault

Length of output: 184

🏁 Script executed:

# Find and read the run.py file
cat backup_existing_project/backend/run.py

Repository: opensource-society/notesvault

Length of output: 173

🏁 Script executed:

# Also check the README.md context around lines 145-146
sed -n '140,150p' README.md

Repository: opensource-society/notesvault

Length of output: 310

Remove or correct the --port example on lines 145–146 since run.py does not parse CLI arguments.

The run.py file calls app.run(debug=True) with no argument parsing. The command python3 run.py --port 5001 will not work as documented—the --port flag will be ignored. Either update the documentation to show the supported way to change the port (e.g., environment variable if the app supports it, or modify the code directly), or add argument parsing to run.py to actually handle --port.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 145 - 146, The README shows using `python3 run.py
--port 5001` but run.py currently calls app.run(debug=True) and does not parse
CLI args, so the flag is ignored; either update the README to remove the
`--port` example and document the supported method to change the port (e.g., set
an environment variable or edit the port in the file) or modify run.py to accept
a --port argument and pass it into app.run(port=...) (look for the main entry
where app.run(debug=True) is called and the module name run.py to implement
argument parsing or adjust the docs accordingly).


**Command not found: python or pip**
- Use `python3` and `pip3` instead
- Verify Python 3 is installed: `python3 --version`

**npm install fails**
- Clear npm cache: `npm cache clean --force`
- Delete `node_modules` and `package-lock.json`, then try again

**Module not found errors on backend**
- Ensure virtual environment is activated (should see `(venv)` in terminal)
- Reinstall requirements: `pip install -r requirements.txt --force-reinstall`

---

## 📜 Available Scripts
Expand Down