diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..561a1e9 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +18.20.3 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b61d616..118a014 100644 --- 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//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 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 + ``` +5. Open a Pull Request from `:` 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 index 983e3bc..0bcb7db 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,43 @@ # 🌟 **GitHub Tracker** 🌟 +## 🚩 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//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 - Stars - Forks - Issues - Open Pull Requests - Closed Pull Requests + Stars + Forks + Issues + Open Pull Requests + Closed Pull Requests @@ -41,33 +78,87 @@ 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 ). +If the backend runs locally, it typically listens on (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 @@ -75,10 +166,15 @@ This project uses the Jasmine framework for backend unit and integration tests. - **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 @@ -86,14 +182,25 @@ npm install --save-dev jasmine @types/jasmine supertest express-session passport ```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. diff --git a/package.json b/package.json index f2d89f5..7cfd7e0 100644 --- 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",