GitMetricsLab · rushi-018 · Aug 23, 2025 · Aug 23, 2025 · Aug 23, 2025 · Aug 23, 2025
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+18.20.3
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -38,6 +38,59 @@ 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 "docs(readme): add contributor quick-start"
+   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
+   # Note: use --force-with-lease only on your own topic branch after a rebase.
+   # Avoid force-pushing shared branches.
+   ```
+
+### 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 [Conventional Commits](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).
+
 ### 🧭 First-Time Contribution Steps
 
 1. **Fork the Repository** 🍴  

diff --git a/README.md b/README.md
@@ -1,6 +1,43 @@
 # 🌟 **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
+  ```
+  If you already pushed before the rebase:
+  ```bash
+  git push --force-with-lease
+  ```
+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! 🚀👩‍💻
@@ -20,11 +57,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>
@@ -41,59 +78,129 @@ 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
-$ git clone https://github.com/yourusername/github-tracker.git
+npm install
+cd backend && npm install
 ```
 
-2. Navigate to the project directory:
+### 2. Configure environment variables (backend)
+Copy the sample env file and set required variables:
 ```bash
-$ cd github-tracker
+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`)
 
-3. Run the frontend
+### 3. Start the backend server
+In the `backend` folder:
 ```bash
-$ npm i
-$ npm run dev
+npm start
 ```
 
-4. Run the backend
+### 4. Start the frontend development server
+Open a new terminal in the project root:
 ```bash
-$ npm i
-$ npm start
+npm run dev
+```
+
+### 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`).
+
+> **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:
+
+> Requires Docker Compose v2 (Docker Desktop or standalone Compose v2 CLI).
+> See https://docs.docker.com/compose/ for installation and upgrade instructions.
+
+```bash
+# Dev profile (hot reload etc.)
+npm run docker:dev
+
+# Production-like profile
+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:
+  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
+  ```
 
 ### 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:
@@ -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>

diff --git a/package.json b/package.json
@@ -3,11 +3,17 @@
   "private": true,
   "version": "0.0.0",
   "type": "module",
+  "engines": {
+    "node": "18.20.x"
+  },
   "scripts": {
     "dev": "vite --host",
     "build": "vite build",
     "lint": "eslint .",
     "preview": "vite preview",
+    "setup": "npm install && npm --prefix backend install",
+    "setup:ci": "npm ci && npm --prefix backend ci",
+    "backend:install": "npm --prefix backend install",
     "docker:dev": "docker compose --profile dev up --build",
     "docker:prod": "docker compose --profile prod up -d --build"
   },
@@ -45,6 +51,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",