From 73909197f599f503ab5367a53e8cff12df9a526c Mon Sep 17 00:00:00 2001 From: Prerak Yadav Date: Wed, 17 Jun 2026 06:58:01 +0530 Subject: [PATCH] docs(contributing): add FAQ for new and GSSoC contributors Document common setup, assignment, PR, and scoring questions and align auto-unassign timing with the 7-day bot rule. --- CONTRIBUTING.md | 222 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 220 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f3c3ac73..dbbced620 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,6 +50,7 @@ Please note that this project is released with a [Code of Conduct](CODE_OF_CONDU 7. [Issue Labels & GSSoC Levels](#7-issue-labels--gssoc-levels) 8. [Pull Request (PR) Checklist](#8-pull-request-pr-checklist) 9. [Self-Hosting & Deployment](#9-self-hosting--deployment) +10. [Frequently Asked Questions (FAQ)](#10-frequently-asked-questions-faq) --- @@ -181,9 +182,10 @@ For contributors joining through GirlScript Summer of Code (GSSoC), we map issue | `gssoc:level3` | **Advanced** — Complex logic, API integrations, deep layout refactoring | **55** | ### Guidelines: -* **One Issue at a Time**: You can only be assigned to one issue at a time. -* **Auto-unassignment**: If there is no progress or communication on an assigned issue within **3 days**, it will be unassigned and given to another contributor. +* **One Issue at a Time**: Prefer working on one issue at a time so reviews stay focused. +* **Auto-unassignment**: If you are assigned but do not open a PR within **7 days**, the issue-assignment bot will unassign you so others can pick it up. Still working on it? Comment on the issue and request re-assignment. * **Link Issue to PR**: Ensure your pull request description explicitly links to your assigned issue (e.g. `Closes #45`). +* **GSSoC scoring labels**: Maintainers apply `level:*` difficulty labels and `gssoc:approved` on your PR at merge time so it counts toward GSSoC scoring. See [FAQ — GSSoC 2026](#gssoc-2026) for details. --- @@ -212,6 +214,222 @@ For guides on self-hosting DevTrack or deploying it manually, please check the [ --- +## 10. Frequently Asked Questions (FAQ) + +Answers to the most common questions from new contributors and GSSoC participants. If your question is not covered here, ask in [GitHub Discussions](https://github.com/Priyanshu-byte-coder/devtrack/discussions) or on the GSSoC Discord. + +### Getting Started + +
+Do I need to be assigned to an issue before I start coding? + +Yes. Comment on the issue you want to work on and wait for the assignment bot to confirm. The bot assigns you when your comment includes phrases such as: + +- `I'd like to work on this` +- `assign me` +- `I can work on this` + +Do not open a PR for an issue that is already assigned to someone else. +
+ +
+Can I work on multiple issues at the same time? + +Prefer one issue at a time so reviews stay manageable. The per-contributor assignment limit is temporarily disabled, but maintainers may still ask you to finish an in-progress issue before picking up another. +
+ +
+Should I use npm or pnpm? + +CI runs `npm ci` against `package-lock.json`, and [DEVELOPMENT.md](./DEVELOPMENT.md) uses `npm` commands. For the closest match with CI, use **npm**: + +```bash +npm install +npm run dev +``` + +Some sections of this guide reference `pnpm`; either package manager works locally, but **do not commit conflicting lockfile changes**. Do not mix `package-lock.json` and `pnpm-lock.yaml` updates in the same PR. +
+ +
+Which environment variables are required? + +At minimum you need Supabase credentials, NextAuth settings, GitHub OAuth keys, and `ENCRYPTION_KEY` to sign in and load the dashboard. See the full table in [Section 3 — Environment Variables Guide](#3-environment-variables-guide). + +Optional variables (`GROQ_API_KEY`, Upstash Redis, `GITHUB_TOKEN`, etc.) enable extra features but are not required for basic local development. +
+ +
+Where is the full local setup guide? + +- **[DEVELOPMENT.md](./DEVELOPMENT.md)** — step-by-step setup from clone to running app +- **[docs/architecture.md](./docs/architecture.md)** — how pages, API routes, and Supabase fit together +- **[docs/self-hosting.md](./docs/self-hosting.md)** — deployment and production env vars +
+ +
+I'm new to open source — where should I start? + +Browse [good first issues](https://github.com/Priyanshu-byte-coder/devtrack/issues?q=label%3A%22good+first+issue%22), read [docs/architecture.md](./docs/architecture.md), and pick a `gssoc:level1` or documentation issue if you are participating in GSSoC. +
+ +### Issues and PRs + +
+How do I claim an issue? + +1. Find an open, unassigned issue. +2. Comment with your intent (e.g. `I'd like to work on this issue. I'm a GSSoC'26 contributor.`). +3. Wait for the bot to assign you and add the `gssoc:assigned` label. +4. Create a branch, implement the change, and open a PR linking the issue (`Closes #123`). +
+ +
+How long do I have before I lose my assignment? + +You have **7 days** from assignment to open a PR. If no PR is linked within that window, the auto-unassign bot removes your assignment so another contributor can take the issue. If you need more time, comment on the issue before the deadline. +
+ +
+Which branch should my PR target? + +Always open PRs against **`main`** on the upstream repository (`Priyanshu-byte-coder/devtrack`). Never push directly to `main` on upstream — work on a feature branch in your fork instead. +
+ +
+Should I use feat/ or feature/ for branch names? + +Prefer the prefixes in [Section 5](#5-branch-naming-conventions): `feat/`, `fix/`, `docs/`, `test/`, `refactor/`. Example: `docs/contributing-faq`. +
+ +
+What must my pull request include? + +- A clear title and description +- `Closes #` in the PR body +- Passing CI checks (lint, type-check, tests, build) +- Screenshots or a short GIF for UI changes +- Conventional commit messages on your branch +
+ +
+How do I keep my fork up to date with upstream? + +```bash +git fetch upstream +git checkout main +git rebase upstream/main +git push origin main +``` + +Before opening or updating a PR, rebase your feature branch onto the latest `upstream/main`. +
+ +### GSSoC 2026 + +
+How do GSSoC points work for DevTrack? + +Points depend on issue difficulty and PR quality labels applied by maintainers at merge time. The assignment bot and GSSoC label automation help track your work, but **maintainers must add `level:*` and `gssoc:approved` labels before your PR counts toward scoring**. +
+ +
+What labels matter for GSSoC scoring? + +| Label | Purpose | +| :--- | :--- | +| `level:beginner` | 20 pts | +| `level:intermediate` | 35 pts | +| `level:advanced` | 55 pts | +| `level:critical` | 80 pts | +| `quality:clean` | ×1.2 multiplier (optional) | +| `quality:exceptional` | ×1.5 multiplier (optional) | +| `gssoc:approved` | **Required** for the PR to score | +| `gssoc:invalid` / `gssoc:spam` / `gssoc:ai-slop` | Does not score | + +Issue labels such as `gssoc:level1` indicate estimated difficulty; final scoring labels are applied on the merged PR. +
+ +
+Is documentation-only work valid for GSSoC? + +Yes. Documentation improvements are valuable contributions. Use a `docs/` branch prefix, and your PR will receive a `type:docs` label when merged. +
+ +
+Should I mention GSSoC in my issue comment or PR? + +Yes — mention that you are a GSSoC'26 contributor when requesting assignment (e.g. `I'm a GSSoC'26 contributor and I would like to work on this issue.`). Always link the issue in your PR with `Closes #`. +
+ +
+What happens after my PR is approved? + +A maintainer merges your PR and applies the appropriate `level:*` and `gssoc:approved` labels. If those labels are missing after approval, the GSSoC bot will remind maintainers so your contribution counts. +
+ +### Troubleshooting + +
+My pre-commit or Husky hook failed — what do I do? + +DevTrack runs ESLint and formatting checks before commits. See **[docs/HUSKY_TROUBLESHOOTING.md](./docs/HUSKY_TROUBLESHOOTING.md)** for step-by-step fixes, including permission errors on Linux/macOS and Windows-specific issues. +
+ +
+CI is failing on lint or type-check — how do I fix it locally? + +Run the same checks CI uses: + +```bash +npm run lint +npm run type-check +npm run test +npm run build +``` + +Fix all reported errors before pushing again. +
+ +
+GitHub OAuth login is not working locally — what should I check? + +Verify the following in [Section 1 — Prerequisites](#1-prerequisites): + +- GitHub OAuth **callback URL** is exactly `http://localhost:3000/api/auth/callback/github` +- `NEXTAUTH_URL` is `http://localhost:3000` +- `GITHUB_ID` and `GITHUB_SECRET` match your OAuth app +- `.env.local` exists and the dev server was restarted after editing env vars +
+ +
+Where can I ask for help if I'm stuck? + +- **[GitHub Discussions](https://github.com/Priyanshu-byte-coder/devtrack/discussions)** — questions, ideas, and community help +- **Comment on your assigned issue** — maintainers and other contributors can guide you +- **GSSoC Discord** — see [docs/HUSKY_TROUBLESHOOTING.md](./docs/HUSKY_TROUBLESHOOTING.md) for community links +- **[Open an issue](https://github.com/Priyanshu-byte-coder/devtrack/issues/new/choose)** — for bugs or unclear documentation +
+ +
+My PR has merge conflicts — how do I resolve them? + +Sync with upstream and rebase your branch: + +```bash +git fetch upstream +git rebase upstream/main +# resolve conflicts in your editor, then: +git add . +git rebase --continue +git push --force-with-lease origin your-branch-name +``` + +If you are unsure how to resolve a conflict, ask in your PR or issue before force-pushing. +
+ +--- + Thank you for helping make DevTrack better! Happy coding! 🚀