Contribution Workflow
Follow this flow exactly to avoid merge conflicts, keep contributions clean, and make sure your JSON shows correctly on the index page.
0) Mandatory First Step: Issue First, Then PR
- Open a new Issue with your name and file plan.
- Wait for mentor/admin assignment on that Issue.
- Only after assignment, create your branch and start editing files.
- After push, open PR and mention the Issue number (example: Closes #12).
1) Branch and File Naming Rules
- Use your own name for branch: your-name (example: john-doe).
- Use same name for both files: data/your-name.json and portfolios/your-name.html.
- Your portfolio must be a single HTML file (HTML/CSS/JS in one file), for example: portfolios/john-doe.html.
- Portfolio files must be added only inside the portfolios folder.
- Do not edit shared files unless a mentor asks.
1.1) Important: Automatic Updates (NO index.html Editing Needed!)
- When you add data/your-name.json and push to your branch
- The JavaScript script automatically discovers your JSON file from the data/ folder
- It reads your JSON data (name, year, intro, portfolio path)
- It dynamically generates your card with proper layout and spacing
- Your card appears on the index page instantly!
- No merge conflicts, no manual HTML editing
Your JSON File Format:
{\n "name": "Your Name",\n "year": "1st Year CSE",\n "intro": "Your short intro about yourself",\n "portfolio": "portfolios/your-name.html"\n}\n2) First Three Example Structures (Use the same pattern)
Example 1
Branch: john-doe
Files: data/john-doe.json, portfolios/john-doe.html
Example 2
Branch: karthik
Files: data/karthik.json, portfolios/karthik.html
Example 3
Branch: rahul
Files: data/rahul.json, portfolios/rahul.html
2.1) Why You Don't Edit index.html (Auto-Discovery System)
- Automatic Discovery: The script.js scans the data/ folder for JSON files
- Dynamic Card Generation: It reads your JSON and creates your card automatically
- Smart Layout: Cards are sorted alphabetically and auto-adjust spacing
- Error Handling: If JSON is malformed, it shows a clear message
- GitHub API Fallback: Even works if directory listing is disabled
You push your files → JavaScript runs → Discovers data/your-name.json → Reads it → Creates card → Displays on page 🎉
3) Add Upstream Remote (Do this once after cloning)
What is upstream? Upstream is the original repository. You need to add it so you can sync with the latest changes from the main project.
# Add upstream remote (do this only once)
git remote add upstream <original-repository-url>
# Verify it was added correctly
git remote -v
Expected Output:
origin https://github.com/your-username/portfolio-showcase.git (fetch)
origin https://github.com/your-username/portfolio-showcase.git (push)
upstream https://github.com/original-owner/portfolio-showcase.git (fetch)
upstream https://github.com/original-owner/portfolio-showcase.git (push)
Fix: You already added upstream before. Run
git remote -v to verify it's correct. If wrong, remove and re-add:git remote remove upstream
git remote add upstream <correct-url>4) Command Flow (Run in this order)
# Clone once (skip if already cloned)
git clone <repository-url>
cd portfolio-showcase
# Add upstream remote (if not done yet)
git remote add upstream <original-repository-url>
# Create Issue first on GitHub website and get assigned
# Optional GitHub CLI alternative:
# gh issue create --title "Add your-name portfolio" --body "I will add data/your-name.json and portfolios/your-name.html"
# Start coding only after assignment.
# Always sync first
git checkout main
git pull origin main
# Create and switch to your own branch
git checkout -b your-name
# Pull again to be safe before editing
git pull origin main
# Make your changes in only these files
# portfolios/your-name.html
# data/your-name.json
# Check what changed
git status
# Add only your own files (example)
git add portfolios/john-doe.html data/john-doe.json
# Commit
git commit -m "Add john-doe portfolio"
# Push to your branch
git push -u origin your-name
Start editing only after issue assignment. After you push your branch, raise PR using the GitHub website only (not CLI) and use the PR template from templates page.
5) Common Errors & Fixes
❌ Error: "fatal: not a git repository"
Cause: You're not in correct folder.
Fix:
cd portfolio-showcase
git status❌ Error: "Your local changes would be overwritten"
Cause: Unsaved changes exist.
Fix:
git add .
git commit -m "Save changes"
git pull origin main❌ Error: "no upstream branch"
Cause: Push without -u flag.
Fix:
git push -u origin your-name❌ Merge Conflicts
Cause: Same file modified elsewhere.
Fix: Remove conflict markers, keep code, then:
git add .
git commit -m "Resolved conflict"
git push origin your-name6) Automatic Updates from Upstream
Keep your fork synced with latest changes from original project:
# Fetch and merge upstream changes
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
# Or use this one-liner
git fetch upstream && git checkout main && git merge upstream/main && git push origin main
Run this regularly before making new changes!
7) Final Step
Open a Pull Request from your-name branch to main on GitHub website, and link your assigned Issue in PR description using Closes #issue-number.
8) Technical Deep Dive: How Auto-Discovery Works
Step 1: File Discovery
The script.js scans the data/ folder and finds all JSON files automatically using GitHub API.
Step 2: JSON Loading
Each JSON file is fetched and parsed. Your contributor data is extracted safely.
Step 3: Card Generation
Dynamic HTML cards are created from your JSON data with proper escaping and error handling.
Step 4: Auto-Rendering
Cards are sorted alphabetically and displayed with smooth animations and responsive layout.
Why This Design? This approach avoids merge conflicts, makes contribution easy, and teaches you real-world practices like API integration and dynamic content generation!