Skip to content

docs: add Quick Start for Contributors and clarify setup steps #198

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
rushi-018 wants to merge 7 commits into
base: main
Choose a base branch
from
Open

docs: add Quick Start for Contributors and clarify setup steps #198

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b9e6ef3
docs: add Quick Start for Contributors and clarify setup steps
rushi-018 Aug 23, 2025
72ec866
docs(readme): address review feedback (upstream sync, test config, UR…
rushi-018 Aug 23, 2025
3613b39
docs(readme,contrib): address review (workflow, env, docker, tests); …
rushi-018 Aug 23, 2025
aae0906
docs(readme,contrib): address review (workflow, env, docker, tests); …
rushi-018 Aug 23, 2025
d64e3a7
docs(readme,contrib): address review (workflow, env, docker, tests); …
rushi-018 Aug 23, 2025
ebf9bd5
docs: address review (cross-env note, badges, rebase tip); chore: add…
rushi-018 Aug 23, 2025
26f2df0
docs: address review (compose v2 note, rebase tip, commit example); c…
rushi-018 Aug 23, 2025
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
1 change: 1 addition & 0 deletions .nvmrc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
18.20.3
51 changes: 51 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,57 @@ github_tracker/

## 🤝 How to Contribute

### Branching Workflow

1. Fork this repository to your GitHub account.
2. Clone your fork locally:
```bash
git clone https://github.com/<your-username>/github_tracker.git
cd github_tracker
```
3. Add the upstream remote and sync with the latest main branch:
```bash
git remote add upstream https://github.com/GitMetricsLab/github_tracker.git
git fetch upstream
git checkout -b <topic-branch> upstream/main
```
4. Commit your work to your topic branch and push to your fork:
```bash
git add .
git commit -m "feat: add contributor quick-start to README"
git push -u origin <topic-branch>
```
5. Open a Pull Request from `<your-username>:<topic-branch>` to `GitMetricsLab:main`.
6. Keep your branch up to date with the latest upstream changes:
```bash
git fetch upstream
git rebase upstream/main
# if you've already pushed, use a safe update:
git push --force-with-lease
```

### Commit Conventions

Use Conventional Commits. Examples:

- `docs(readme): improve setup instructions`
- `fix(auth): handle missing session cookie`
- `feat(tracker): add contributor activity chart`

This helps with change logs and automated releases. See https://www.conventionalcommits.org/.

### Sign-offs / DCO (Optional)

If your organization requires a Developer Certificate of Origin (DCO), add a sign-off to each commit:

```bash
git commit -s -m "docs(readme): clarify install steps"
```

### Link Back to Quick Start

For first-time setup and commands, see the [Quick Start](README.md#quick-start-for-contributors).

Comment thread
coderabbitai[bot] marked this conversation as resolved.
### 🧭 First-Time Contribution Steps

1. **Fork the Repository** 🍴
Expand Down
163 changes: 135 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,39 @@
# 🌟 **GitHub Tracker** 🌟
<!-- top -->

## 🚩 Quick Start for Contributors

Want to contribute? Here’s how to get started:

1. **Fork** this repository on GitHub.
2. **Clone** your fork:
```bash
git clone https://github.com/<your-username>/github_tracker.git
cd github_tracker
```
3. **Add the upstream remote and sync** (original repository):
```bash
git remote add upstream https://github.com/GitMetricsLab/github_tracker.git
git fetch upstream
# create your branch from the latest upstream main
git checkout -b my-first-contribution upstream/main
```
Later, to refresh your branch:
```bash
git fetch upstream && git rebase upstream/main
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
4. **Make your changes** (e.g., edit `README.md` to improve instructions).
5. **Commit and push**:
```bash
git add .
git commit -m "docs(readme): improve setup instructions"
git push -u origin my-first-contribution
```
6. **Open a Pull Request** from your branch to the main repository.

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details!


**Track Activity of Users on GitHub**

Welcome to **GitHub Tracker**, a web app designed to help you monitor and analyze the activity of GitHub users. Whether you’re a developer, a project manager, or just curious, this tool simplifies tracking contributions and activity across repositories! 🚀👩‍💻
Expand All @@ -20,11 +53,11 @@ Welcome to **GitHub Tracker**, a web app designed to help you monitor and analyz
</thead>
<tbody>
<tr>
<td><img alt="Stars" src="https://img.shields.io/github/stars/mehul-m-prajapati/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Forks" src="https://img.shields.io/github/forks/mehul-m-prajapati/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Issues" src="https://img.shields.io/github/issues/mehul-m-prajapati/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Open Pull Requests" src="https://img.shields.io/github/issues-pr/mehul-m-prajapati/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Closed Pull Requests" src="https://img.shields.io/github/issues-pr-closed/mehul-m-prajapati/github_tracker?style=flat&color=critical&logo=github"/></td>
<td><img alt="Stars" src="https://img.shields.io/github/stars/GitMetricsLab/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Forks" src="https://img.shields.io/github/forks/GitMetricsLab/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Issues" src="https://img.shields.io/github/issues/GitMetricsLab/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Open Pull Requests" src="https://img.shields.io/github/issues-pr/GitMetricsLab/github_tracker?style=flat&logo=github"/></td>
<td><img alt="Closed Pull Requests" src="https://img.shields.io/github/issues-pr-closed/GitMetricsLab/github_tracker?style=flat&color=critical&logo=github"/></td>
</tr>
</tbody>
</table>
Expand All @@ -41,59 +74,133 @@ Welcome to **GitHub Tracker**, a web app designed to help you monitor and analyz
---

## 🚀 Setup Guide
1. Clone the repository to your local machine:

### 1. Install dependencies for both frontend and backend

First, switch to the project’s Node.js version (from `.nvmrc`) if you use nvm:
```bash
nvm use
```

Preferred (one command):
```bash
npm run setup
```

Fallback (manual):
```bash
npm install
cd backend && npm install
```
> Tip: Use the project’s Node.js version. If you’ve set it in `.nvmrc` or `package.json#engines`, nvm will pick it up.
>
> With nvm:
> ```bash
> nvm use
> ```

Comment thread
coderabbitai[bot] marked this conversation as resolved.
### 2. Configure environment variables (backend)
Copy the sample env file and set required variables:
```bash
$ git clone https://github.com/yourusername/github-tracker.git
cp backend/.env.sample backend/.env
```
PowerShell (Windows):
```powershell
Copy-Item backend/.env.sample backend/.env
```
Then edit `backend/.env` and set at least:
- `MONGO_URI` (e.g., `mongodb://127.0.0.1:27017/githubTracker`)
- `SESSION_SECRET` (e.g., a long random string)
- `PORT` (e.g., `5000`)

Comment thread
coderabbitai[bot] marked this conversation as resolved.
2. Navigate to the project directory:
### 3. Start the backend server
In the `backend` folder:
```bash
$ cd github-tracker
npm start
```

3. Run the frontend
### 4. Start the frontend development server
Open a new terminal in the project root:
```bash
$ npm i
$ npm run dev
npm run dev
```

4. Run the backend
### 5. Open the app in your browser
Visit the URL shown in the terminal (usually <http://localhost:5173>).
If the backend runs locally, it typically listens on <http://localhost:5000> (or the value of `PORT` in your `.env`).

Comment thread
coderabbitai[bot] marked this conversation as resolved.
> **Note:** Make sure MongoDB is running locally (default: `mongodb://127.0.0.1:27017`).
>
> Optional: Run MongoDB with Docker
> ```bash
> docker volume create github-tracker-mongo
> docker run --name github-tracker-mongo \
> -p 27017:27017 \
> -v github-tracker-mongo:/data/db \
> -d mongo:6
>
> # Then, point your app at this database, for example:
> export MONGO_URI="mongodb://127.0.0.1:27017/githubTracker"
> ```

Alternatively, to start the full stack with Compose:

```bash
$ npm i
$ npm start
# Dev profile (hot reload etc.)
npm run docker:dev

# Production-like profile
npm run docker:prod
```
Comment on lines +146 to 155
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Aug 23, 2025

Choose a reason for hiding this comment

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

💡 Verification agent

🧩 Analysis chain

Verify compose profiles exist (dev/prod) and document prerequisites if needed

The scripts reference --profile dev and --profile prod. Please verify those profiles are present in your compose file and call it out if Docker Desktop/Compose v2 is required.

🏁 Script executed:

#!/bin/bash
# Verify compose file and profiles
fd -a -t f -g "docker-compose*.yml" -g "compose*.yml" || true
rg -n -C2 -i 'profiles:\s*\n\s*-+\s*dev|profiles:\s*\n\s*-+\s*prod' -g 'docker-compose*.yml' -g 'compose*.yml' || true

Length of output: 474

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Searching for Docker Compose files..."
compose_files=$(find . -maxdepth 4 -type f \( -name 'docker-compose*.yml' -o -name 'compose*.yml' \) || true)

if [ -z "$compose_files" ]; then
  echo "No Compose files found in the repository."
  exit 0
fi

for file in $compose_files; do
  echo
  echo "----- Checking $file -----"
  
  echo "Looking for 'dev' profile..."
  if rg -U -n 'profiles:\s*\n\s*-\s*dev' "$file" >/dev/null; then
    echo "  ✓ 'dev' profile found"
  else
    echo "  ✗ 'dev' profile NOT found"
  fi

  echo "Looking for 'prod' profile..."
  if rg -U -n 'profiles:\s*\n\s*-\s*prod' "$file" >/dev/null; then
    echo "  ✓ 'prod' profile found"
  else
    echo "  ✗ 'prod' profile NOT found"
  fi
done

Length of output: 790

Compose profiles verified – add Compose v2 prerequisite

  • Verified that docker-compose.yml defines both dev and prod profiles.
  • Profiles require Docker Compose v2 (either via Docker Desktop v3.0+ or the standalone v2 CLI).
  • Please update the README.md snippet (lines 146–154) to call out this prerequisite so users don’t encounter errors when running npm run docker:dev or npm run docker:prod.
🤖 Prompt for AI Agents 
In README.md around lines 146 to 154, the compose snippet omits a prerequisite
that the user must have Docker Compose v2 (Docker Desktop v3.0+ or the
standalone v2 CLI) to use named profiles; add a one-line note immediately above
the code block stating that Compose v2 is required and optionally link to
installation/update instructions for Docker Desktop or the Compose v2 CLI so
users know how to upgrade before running `npm run docker:dev` or `npm run
docker:prod`.


## 🧪 Backend Unit & Integration Testing with Jasmine

This project uses the Jasmine framework for backend unit and integration tests. The tests cover:
- User model (password hashing, schema, password comparison)
- Authentication routes (signup, login, logout)
- [User model (password hashing, schema, password comparison)](spec/user.model.spec.cjs)
- [Authentication routes (signup, login, logout)](spec/auth.routes.spec.cjs)
- Passport authentication logic (via integration tests)

### Prerequisites
- **Node.js** and **npm** installed
- **MongoDB** running locally (default: `mongodb://127.0.0.1:27017`)

### Installation
Install all required dependencies:
```sh
npm install
npm install --save-dev jasmine @types/jasmine supertest express-session passport passport-local bcryptjs
Install dependencies (root and backend) if you haven’t already:
```bash
npm run setup
```
Jasmine is already configured in the repo; run it via `npx` or an npm script to avoid global installs:
```bash
npx jasmine --config=spec/support/jasmine.mjs
# or add to package.json:
# "scripts": { "test": "jasmine --config=spec/support/jasmine.mjs" }
```

### Running the Tests
1. **Start MongoDB** (if not already running):
```sh
mongod
```
2. **Run Jasmine tests:**
```sh
npx jasmine
```
2. **Run Jasmine tests (from the repository root) with the MJS config:**

macOS/Linux (Bash):
```bash
# Use a test database (e.g., github_tracker_test) to avoid clobbering dev data
MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test" npx jasmine --config=spec/support/jasmine.mjs
# Or cross-platform with one command:
# (one-time) npm install --save-dev cross-env # in the repository root
npx cross-env MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test" jasmine --config=spec/support/jasmine.mjs
```

Windows (PowerShell):
```powershell
# Use a test database (e.g., github_tracker_test) to avoid clobbering dev data
$env:MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test"; npx jasmine --config=spec/support/jasmine.mjs
```
Comment on lines +187 to +199
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Aug 23, 2025

Choose a reason for hiding this comment

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

💡 Verification agent

🧩 Analysis chain

Ensure cross-env is available or provide install hint

The cross-platform example uses cross-env; verify it’s a devDependency or add a one-line install hint.

Verification script:

Optional README tweak if missing:

-  npx cross-env MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test" jasmine --config=spec/support/jasmine.mjs
+  # Requires cross-env (install once: npm i -D cross-env)
+  npx cross-env MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test" jasmine --config=spec/support/jasmine.mjs

🏁 Script executed:

#!/bin/bash
set -euo pipefail
echo "Checking for cross-env in root or backend package.json..."
rg -n '"cross-env"\s*:' -g 'package.json' -g 'backend/package.json' -n -C1 || {
  echo "cross-env not found in devDependencies. Consider adding:"; 
  echo 'npm install -D cross-env';
  exit 1;
}

Length of output: 408

Add cross-env as a devDependency and surface an install hint in the README

The verification script confirmed that cross-env is not currently declared in your devDependencies. Without it, the cross-platform example will fail for users on non-Unix shells.

• Package manifest

  • In your package.json (root or backend/), add cross-env to devDependencies: 
    npm install --save-dev cross-env

• README.md (Lines 186–198)

  • Update the Bash/PowerShell snippet to call out the one-time install. For example: 
      # Or cross-platform with one command:
- npx cross-env MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test" jasmine --config=spec/support/jasmine.mjs
+ # Requires cross-env (install once: npm i -D cross-env)
+ npx cross-env MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test" jasmine --config=spec/support/jasmine.mjs
🤖 Prompt for AI Agents 
In README.md around lines 186–198 the cross-platform test example uses cross-env
but the package.json does not declare cross-env as a devDependency; add
cross-env to your devDependencies in the repository package.json where tests are
executed (root or backend) by running the one-time install (npm install
--save-dev cross-env), and update the README snippet to mention this one-time
install step and call out which package.json to update so users on Windows can
run the cross-platform example successfully.


### Test Files
- `spec/user.model.spec.cjs` — Unit tests for the User model
- `spec/auth.routes.spec.cjs` — Integration tests for authentication routes
- [`spec/user.model.spec.cjs`](spec/user.model.spec.cjs) — Unit tests for the User model
- [`spec/auth.routes.spec.cjs`](spec/auth.routes.spec.cjs) — Integration tests for authentication routes

### Jasmine Configuration
The Jasmine config (`spec/support/jasmine.mjs`) is set to recognize `.cjs`, `.js`, and `.mjs` test files:
Expand Down Expand Up @@ -122,7 +229,7 @@ spec_files: [
- Make sure you show some love by giving ⭐ to our repository.

<div align="center">
<a href="https://github.com/mehul-m-prajapati/github_tracker">
<a href="https://github.com/GitMetricsLab/github_tracker">
<img src="https://contrib.rocks/image?repo=GitMetricsLab/github_tracker&&max=1000" />
</a>
</div>
Expand Down
2 changes: 2 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"build": "vite build",
"lint": "eslint .",
"preview": "vite preview",
"setup": "npm install && npm --prefix backend install",
"docker:dev": "docker compose --profile dev up --build",
"docker:prod": "docker compose --profile prod up -d --build"
},
Expand Down Expand Up @@ -45,6 +46,7 @@
"eslint-plugin-react": "^7.37.2",
"eslint-plugin-react-hooks": "^5.0.0",
"eslint-plugin-react-refresh": "^0.4.14",
"cross-env": "^7.0.3",
"express-session": "^1.18.2",
"globals": "^15.11.0",
"jasmine": "^5.9.0",
Expand Down