Docs/improve contributing setup 2610 - #2637
Closed
Asritha11111 wants to merge 6 commits into
Closed
Conversation
github-actions
Bot
added
type:bug
GSSoC Label Checklist 🏷️@Umbrella-io — please apply the appropriate labels before merging: Difficulty (pick one):
Quality (optional):
Validation (required to score):
|
There was a problem hiding this comment.
Pull request overview
This PR primarily expands contributor documentation to improve local setup troubleshooting, while also introducing a small API change in dateUtils (a new exported alias).
Changes:
- Added a new “Troubleshooting Common Issues” section and updated the Table of Contents/section numbering in
CONTRIBUTING.md. - Updated various setup/troubleshooting commands and guidance (with some OS-specific instructions).
- Added
dateDiffas an alias export fordateDiffDaysinsrc/lib/dateUtils.ts.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
CONTRIBUTING.md |
Adds a troubleshooting section and renumbers/updates TOC links to help new contributors resolve common setup problems. |
src/lib/dateUtils.ts |
Exports dateDiff as an alias for dateDiffDays to address an import mismatch. |
Comments suppressed due to low confidence (1)
src/lib/dateUtils.ts:28
- This PR is marked/documented as a docs-only change (setup + troubleshooting), but this adds a new exported API (
dateDiff) insrc/lib/dateUtils.tsand references a different issue (#1879). Consider either (a) updating the PR description/title/scope to include this code change, or (b) moving this alias into a separate PR tied to #1879 to avoid mixing concerns.
* Calculates the start of the week (Monday) in UTC for the given date.
* Adjusts for timezone differences to ensure consistent weekly grouping.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| **Solution:** | ||
|
|
||
| * **macOS/Linux:** Try `sudo pnpm install` or fix npm permissions: |
Comment on lines
+252
to
+255
| Check that you're running the command from the project root directory. | ||
|
|
||
| If using a monorepo, make sure you're in the correct workspace. | ||
|
|
Comment on lines
+136
to
+138
| ```bash | ||
| cp .env.example .env.local | ||
| ``` |
Comment on lines
+213
to
+217
| ```bash | ||
| # Clean install | ||
| rm -rf node_modules pnpm-lock.yaml | ||
| pnpm install | ||
| ``` |
Comment on lines
+258
to
+261
| ```bash | ||
| rm -rf .next | ||
| pnpm dev | ||
| ``` |
Comment on lines
+42
to
+52
| ## 📋 Table of Contents | ||
|
|
||
| 1. [Prerequisites](#1-prerequisites) | ||
| 2. [Local Development Setup](#2-local-development-setup) | ||
| 3. [Environment Variables Guide](#3-environment-variables-guide) | ||
| 4. [Code Style & Standards](#4-code-style--standards) | ||
| 5. [Branch Naming Conventions](#5-branch-naming-conventions) | ||
| 6. [Commit Guidelines](#6-commit-guidelines) | ||
| 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) | ||
| 4. [Troubleshooting Common Issues](#4-troubleshooting-common-issues) | ||
| 5. [Code Style & Standards](#5-code-style--standards) | ||
| 6. [Branch Naming Conventions](#6-branch-naming-conventions) | ||
| 7. [Commit Guidelines](#7-commit-guidelines) | ||
| 8. [Issue Labels & GSSoC Levels](#8-issue-labels--gssoc-levels) | ||
| 9. [Pull Request (PR) Checklist](#9-pull-request-pr-checklist) | ||
| 10. [Self-Hosting & Deployment](#10-self-hosting--deployment) |
Owner
|
CI is failing on this PR. Please fix the TypeScript/test errors before we can merge. Run |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive local development setup instructions and a troubleshooting guide to CONTRIBUTING.md. These additions will help new contributors (especially GSSoC participants) set up the project quickly and resolve common issues without needing to ask for help.
Closes #2610
Type of Change
What Changed
Added "Verifying Your Setup" section with validation commands:
curl)pnpm run check-env)pnpm run type-check)pnpm run test)pnpm run build)Added "Troubleshooting Common Issues" section with solutions for:
pnpm installpermission errors (macOS/Linux/Windows).env.localfileNEXTAUTH_SECRETorENCRYPTION_KEYnot set (with openssl commands)Updated Table of Contents to include the new sections
Added GSSoC Issue Labels section with level points
How to Test
CONTRIBUTING.mdin a Markdown previewer (VS Code preview or GitHub)Expected result: The file renders cleanly with all new sections visible and properly formatted.
Checklist
console.log, debug code, or commented-out blocksnpm run lintpasses locallynpm run type-check)Accessibility (UI changes only)
Additional Context
This PR addresses the most common setup questions asked by new contributors in the community. The troubleshooting section covers 10+ frequent issues that contributors have reported during onboarding. The verification section helps contributors confirm their setup is correct before starting development, reducing the number of "my setup isn't working" questions.