From b9e6ef38b7361d5facccb9b1d8d5f57bebe767bf Mon Sep 17 00:00:00 2001 From: rushi-018 Date: Sat, 23 Aug 2025 12:44:40 +0530 Subject: [PATCH 1/7] docs: add Quick Start for Contributors and clarify setup steps --- README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 983e3bc..bd00aec 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,32 @@ # šŸŒŸ **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. **Create a new branch** for your change: + ```bash + git checkout -b my-first-contribution + ``` +4. **Make your changes** (e.g., edit `README.md` to improve instructions). +5. **Commit and push**: + ```bash + git add . + git commit -m "docs: improve README instructions" + git push 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! šŸš€šŸ‘©ā€šŸ’» @@ -41,28 +67,36 @@ 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 + +In the project root: ```bash -$ git clone https://github.com/yourusername/github-tracker.git +npm install ``` - -2. Navigate to the project directory: +Then in the backend folder: ```bash -$ cd github-tracker +cd backend +npm install ``` -3. Run the frontend +### 2. Start the backend server +In the `backend` folder: ```bash -$ npm i -$ npm run dev +npm start ``` -4. Run the backend +### 3. Start the frontend development server +Open a new terminal in the project root: ```bash -$ npm i -$ npm start +npm run dev ``` +### 4. Open the app in your browser +Visit the URL shown in the terminal (usually http://localhost:5173). + +> **Note:** Make sure MongoDB is running locally (default: `mongodb://127.0.0.1:27017`). + ## šŸ§Ŗ Backend Unit & Integration Testing with Jasmine This project uses the Jasmine framework for backend unit and integration tests. The tests cover: From 72ec866e38c346824db1b938a18e5a9179668575 Mon Sep 17 00:00:00 2001 From: rushi-018 Date: Sat, 23 Aug 2025 15:37:15 +0530 Subject: [PATCH 2/7] docs(readme): address review feedback (upstream sync, test config, URLs, docker tip) --- README.md | 49 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index bd00aec..57f0f59 100644 --- a/README.md +++ b/README.md @@ -11,18 +11,25 @@ Want to contribute? Hereā€™s how to get started: git clone https://github.com//github_tracker.git cd github_tracker ``` -3. **Create a new branch** for your change: +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 + ``` +4. **Create a new branch** for your change (if you didnā€™t in the previous step): ```bash git checkout -b my-first-contribution ``` -4. **Make your changes** (e.g., edit `README.md` to improve instructions). -5. **Commit and push**: +5. **Make your changes** (e.g., edit `README.md` to improve instructions). +6. **Commit and push**: ```bash git add . - git commit -m "docs: improve README instructions" + git commit -m "docs(readme): improve setup instructions" git push origin my-first-contribution ``` -6. **Open a Pull Request** from your branch to the main repository. +7. **Open a Pull Request** from your branch to the main repository. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details! @@ -79,6 +86,12 @@ Then in the backend folder: 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 +> ``` ### 2. Start the backend server In the `backend` folder: @@ -93,9 +106,15 @@ npm run dev ``` ### 4. Open the app in your browser -Visit the URL shown in the terminal (usually http://localhost:5173). +Visit the URL shown in the terminal (usually ). +If the backend runs locally, it typically listens on unless overridden. > **Note:** Make sure MongoDB is running locally (default: `mongodb://127.0.0.1:27017`). +> +> Optional: Run MongoDB with Docker +> ```bash +> docker run --name github-tracker-mongo -p 27017:27017 -d mongo:6 +> ``` ## šŸ§Ŗ Backend Unit & Integration Testing with Jasmine @@ -109,10 +128,14 @@ 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: +Install dependencies (root and backend): ```sh npm install -npm install --save-dev jasmine @types/jasmine supertest express-session passport passport-local bcryptjs +cd backend && npm install +``` +Jasmine is already configured in the repo; if not installed locally, add it as a dev dependency: +```sh +npm install --save-dev jasmine ``` ### Running the Tests @@ -120,10 +143,12 @@ npm install --save-dev jasmine @types/jasmine supertest express-session passport ```sh mongod ``` -2. **Run Jasmine tests:** - ```sh - npx jasmine - ``` +2. **Run Jasmine tests with the MJS config:** + ```sh + # tests should use a test database (e.g., github_tracker_test). Ensure your env/config points to it. + # Example (if your app reads MONGODB_URI): + MONGODB_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 From 3613b39476e858c405976253d02a54458a8a66bc Mon Sep 17 00:00:00 2001 From: rushi-018 Date: Sat, 23 Aug 2025 16:03:59 +0530 Subject: [PATCH 3/7] docs(readme,contrib): address review (workflow, env, docker, tests); chore: add setup script --- .nvmrc | 1 + CONTRIBUTING.md | 42 +++++++++++++++++++++++++++ README.md | 76 +++++++++++++++++++++++++++++++++---------------- package.json | 1 + 4 files changed, 96 insertions(+), 24 deletions(-) create mode 100644 .nvmrc 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..3e1f652 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,6 +38,48 @@ 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 push -u origin + ``` +5. Open a Pull Request from `:` to `GitMetricsLab:main`. + +### 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. + +### 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 in `README.md`. + ### šŸ§­ First-Time Contribution Steps 1. **Fork the Repository** šŸ“ diff --git a/README.md b/README.md index 57f0f59..f6644ce 100644 --- a/README.md +++ b/README.md @@ -18,18 +18,14 @@ Want to contribute? Hereā€™s how to get started: # create your branch from the latest upstream main git checkout -b my-first-contribution upstream/main ``` -4. **Create a new branch** for your change (if you didnā€™t in the previous step): - ```bash - git checkout -b my-first-contribution - ``` -5. **Make your changes** (e.g., edit `README.md` to improve instructions). -6. **Commit and push**: +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 origin my-first-contribution + git push -u origin my-first-contribution ``` -7. **Open a Pull Request** from your branch to the main repository. +6. **Open a Pull Request** from your branch to the main repository. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details! @@ -86,6 +82,10 @@ Then in the backend folder: cd backend npm install ``` +Or, to run both in one go: +```bash +npm run setup +``` > 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: @@ -93,19 +93,33 @@ npm install > nvm use > ``` -### 2. Start the backend server +### 2. Configure environment variables (backend) +Copy the sample env file and set required variables: +```bash +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. Start the backend server In the `backend` folder: ```bash npm start ``` -### 3. Start the frontend development server +### 4. Start the frontend development server Open a new terminal in the project root: ```bash npm run dev ``` -### 4. Open the app in your browser +### 5. Open the app in your browser Visit the URL shown in the terminal (usually ). If the backend runs locally, it typically listens on unless overridden. @@ -113,14 +127,21 @@ If the backend runs locally, it typically listens on unl > > Optional: Run MongoDB with Docker > ```bash -> docker run --name github-tracker-mongo -p 27017:27017 -d mongo:6 +> 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" > ``` ## šŸ§Ŗ 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 @@ -128,13 +149,13 @@ This project uses the Jasmine framework for backend unit and integration tests. - **MongoDB** running locally (default: `mongodb://127.0.0.1:27017`) ### Installation -Install dependencies (root and backend): -```sh +Install dependencies (root and backend) if you havenā€™t already: +```bash npm install cd backend && npm install ``` -Jasmine is already configured in the repo; if not installed locally, add it as a dev dependency: -```sh +Jasmine is already configured in the repo; if missing locally: +```bash npm install --save-dev jasmine ``` @@ -143,16 +164,23 @@ npm install --save-dev jasmine ```sh mongod ``` -2. **Run Jasmine tests with the MJS config:** - ```sh - # tests should use a test database (e.g., github_tracker_test). Ensure your env/config points to it. - # Example (if your app reads MONGODB_URI): +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 MONGODB_URI="mongodb://127.0.0.1:27017/github_tracker_test" npx jasmine --config=spec/support/jasmine.mjs ``` + Windows (PowerShell): + ```powershell + # Use a test database (e.g., github_tracker_test) to avoid clobbering dev data + $env:MONGODB_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: diff --git a/package.json b/package.json index f2d89f5..7492862 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,7 @@ "build": "vite build", "lint": "eslint .", "preview": "vite preview", + "setup": "npm install && cd backend && npm install", "docker:dev": "docker compose --profile dev up --build", "docker:prod": "docker compose --profile prod up -d --build" }, From aae0906a5ea0df3c05a3ca06a4c7a075d2f2e753 Mon Sep 17 00:00:00 2001 From: rushi-018 Date: Sat, 23 Aug 2025 16:27:44 +0530 Subject: [PATCH 4/7] docs(readme,contrib): address review (workflow, env, docker, tests); chore: add setup script --- CONTRIBUTING.md | 6 ++++-- README.md | 31 ++++++++++++++++++------------- package.json | 2 +- 3 files changed, 23 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e1f652..4ada920 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,8 @@ github_tracker/ ``` 4. Commit your work to your topic branch and push to your fork: ```bash + git add . + git commit -m "feat: " git push -u origin ``` 5. Open a Pull Request from `:` to `GitMetricsLab:main`. @@ -73,12 +75,12 @@ This helps with change logs and automated releases. 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" +git commit -s --signoff -m "docs(readme): clarify install steps" ``` ### Link Back to Quick Start -For first-time setup and commands, see the Quick Start in `README.md`. +For first-time setup and commands, see the [Quick Start](README.md#-quick-start-for-contributors). ### šŸ§­ First-Time Contribution Steps diff --git a/README.md b/README.md index f6644ce..0ad7cce 100644 --- a/README.md +++ b/README.md @@ -73,18 +73,14 @@ Welcome to **GitHub Tracker**, a web app designed to help you monitor and analyz ### 1. Install dependencies for both frontend and backend -In the project root: +Preferred (one command): ```bash -npm install +npm run setup ``` -Then in the backend folder: +Fallback (manual): ```bash -cd backend npm install -``` -Or, to run both in one go: -```bash -npm run setup +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. > @@ -121,7 +117,7 @@ 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 unless overridden. +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`). > @@ -137,6 +133,16 @@ If the backend runs locally, it typically listens on unl > # export MONGO_URI="mongodb://127.0.0.1:27017/githubTracker" > ``` +Alternatively, to start the full stack with Compose: + +```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: @@ -151,8 +157,7 @@ This project uses the Jasmine framework for backend unit and integration tests. ### Installation Install dependencies (root and backend) if you havenā€™t already: ```bash -npm install -cd backend && npm install +npm run setup ``` Jasmine is already configured in the repo; if missing locally: ```bash @@ -169,13 +174,13 @@ npm install --save-dev jasmine macOS/Linux (Bash): ```bash # Use a test database (e.g., github_tracker_test) to avoid clobbering dev data - MONGODB_URI="mongodb://127.0.0.1:27017/github_tracker_test" npx jasmine --config=spec/support/jasmine.mjs + MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test" npx jasmine --config=spec/support/jasmine.mjs ``` Windows (PowerShell): ```powershell # Use a test database (e.g., github_tracker_test) to avoid clobbering dev data - $env:MONGODB_URI="mongodb://127.0.0.1:27017/github_tracker_test"; npx jasmine --config=spec/support/jasmine.mjs + $env:MONGO_URI="mongodb://127.0.0.1:27017/github_tracker_test"; npx jasmine --config=spec/support/jasmine.mjs ``` ### Test Files diff --git a/package.json b/package.json index 7492862..0153797 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "build": "vite build", "lint": "eslint .", "preview": "vite preview", - "setup": "npm install && cd backend && npm install", + "setup": "npm install && npm --prefix backend install", "docker:dev": "docker compose --profile dev up --build", "docker:prod": "docker compose --profile prod up -d --build" }, From d64e3a7aaad46faae51122118de818d0d03643b0 Mon Sep 17 00:00:00 2001 From: rushi-018 Date: Sat, 23 Aug 2025 16:38:45 +0530 Subject: [PATCH 5/7] docs(readme,contrib): address review (workflow, env, docker, tests); chore: add setup script --- CONTRIBUTING.md | 15 +++++++++++---- README.md | 32 +++++++++++++++++++++++--------- 2 files changed, 34 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ada920..23b62a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,10 +55,17 @@ github_tracker/ 4. Commit your work to your topic branch and push to your fork: ```bash git add . - git commit -m "feat: " + git commit -m "feat: add contributor quick-start to README" 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 + ``` ### Commit Conventions @@ -68,19 +75,19 @@ Use Conventional Commits. Examples: - `fix(auth): handle missing session cookie` - `feat(tracker): add contributor activity chart` -This helps with change logs and automated releases. +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 --signoff -m "docs(readme): clarify install steps" +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). +For first-time setup and commands, see the [Quick Start](README.md#quick-start-for-contributors). ### šŸ§­ First-Time Contribution Steps diff --git a/README.md b/README.md index 0ad7cce..ade2586 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ Want to contribute? Hereā€™s how to get started: # 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 + ``` 4. **Make your changes** (e.g., edit `README.md` to improve instructions). 5. **Commit and push**: ```bash @@ -49,11 +53,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 @@ -73,10 +77,16 @@ Welcome to **GitHub Tracker**, a web app designed to help you monitor and analyz ### 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 @@ -130,7 +140,7 @@ If the backend runs locally, it typically listens on (or > -d mongo:6 > > # Then, point your app at this database, for example: -> # export MONGO_URI="mongodb://127.0.0.1:27017/githubTracker" +> export MONGO_URI="mongodb://127.0.0.1:27017/githubTracker" > ``` Alternatively, to start the full stack with Compose: @@ -159,9 +169,11 @@ Install dependencies (root and backend) if you havenā€™t already: ```bash npm run setup ``` -Jasmine is already configured in the repo; if missing locally: +Jasmine is already configured in the repo; run it via `npx` or an npm script to avoid global installs: ```bash -npm install --save-dev jasmine +npx jasmine --config=spec/support/jasmine.mjs +# or add to package.json: +# "scripts": { "test": "jasmine --config=spec/support/jasmine.mjs" } ``` ### Running the Tests @@ -175,6 +187,8 @@ npm install --save-dev jasmine ```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): @@ -214,7 +228,7 @@ spec_files: [ - Make sure you show some love by giving ā­ to our repository. From ebf9bd580e3ac17c58e9b6852e952a19b07874ec Mon Sep 17 00:00:00 2001 From: rushi-018 Date: Sat, 23 Aug 2025 17:24:33 +0530 Subject: [PATCH 6/7] docs: address review (cross-env note, badges, rebase tip); chore: add cross-env --- README.md | 1 + package.json | 1 + 2 files changed, 2 insertions(+) diff --git a/README.md b/README.md index ade2586..2ac25e6 100644 --- a/README.md +++ b/README.md @@ -188,6 +188,7 @@ npx jasmine --config=spec/support/jasmine.mjs # 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 ``` diff --git a/package.json b/package.json index 0153797..ca436bb 100644 --- a/package.json +++ b/package.json @@ -46,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", From 26f2df013ab54f7c355a4cb7cd338866db5aaa89 Mon Sep 17 00:00:00 2001 From: rushi-018 Date: Sat, 23 Aug 2025 17:45:50 +0530 Subject: [PATCH 7/7] docs: address review (compose v2 note, rebase tip, commit example); chore: add setup:ci and engines --- CONTRIBUTING.md | 6 ++++-- README.md | 14 +++++++------- package.json | 7 ++++++- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23b62a3..118a014 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,7 +55,7 @@ github_tracker/ 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 commit -m "docs(readme): add contributor quick-start" git push -u origin ``` 5. Open a Pull Request from `:` to `GitMetricsLab:main`. @@ -65,6 +65,8 @@ github_tracker/ 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 @@ -75,7 +77,7 @@ Use Conventional Commits. Examples: - `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/. +This helps with change logs and automated releases. See [Conventional Commits](https://www.conventionalcommits.org/). ### Sign-offs / DCO (Optional) diff --git a/README.md b/README.md index 2ac25e6..0bcb7db 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,10 @@ Want to contribute? Hereā€™s how to get started: ```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 @@ -92,12 +96,6 @@ Fallback (manual): 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 -> ``` ### 2. Configure environment variables (backend) Copy the sample env file and set required variables: @@ -145,6 +143,9 @@ If the backend runs locally, it typically listens on (or 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 @@ -188,7 +189,6 @@ npx jasmine --config=spec/support/jasmine.mjs # 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 ``` diff --git a/package.json b/package.json index ca436bb..7cfd7e0 100644 --- a/package.json +++ b/package.json @@ -3,12 +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": "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" },