Skip to content

Commit 0aedb1b

Browse files
fineanmolfineanmol
committed
📚 Add comprehensive contributor guide
- Clear visual explanation of two contribution options - Step-by-step instructions for adding real names - Common questions and answers - Technical workflow diagram - Examples and templates - Pro tips for contributors
1 parent a74fcfd commit 0aedb1b

File tree

1 file changed

+250
-0
lines changed

1 file changed

+250
-0
lines changed

‎CONTRIBUTOR-GUIDE.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
# 👥 Contributor Recognition Guide
2+
3+
## How You'll Appear on the Contributors Page
4+
5+
### Quick Start: Two Options
6+
7+
```
8+
┌─────────────────────────────────────────────────────────┐
9+
│ Option 1: Quick & Easy │
10+
│ (GitHub Username) │
11+
├─────────────────────────────────────────────────────────┤
12+
│ 1. Make any contribution (code, docs, bug fix) │
13+
│ 2. Submit your PR │
14+
│ 3. Wait 6 hours │
15+
│ 4. You appear as: @yourusername │
16+
└─────────────────────────────────────────────────────────┘
17+
18+
┌─────────────────────────────────────────────────────────┐
19+
│ Option 2: Show Your Real Name │
20+
│ (Recommended! ⭐) │
21+
├─────────────────────────────────────────────────────────┤
22+
│ 1. Make any contribution (code, docs, bug fix) │
23+
│ 2. Edit contributors/contributor-names.json │
24+
│ 3. Add your entry (see example below) │
25+
│ 4. Submit PR with both changes │
26+
│ 5. Wait 6 hours │
27+
│ 6. You appear as: Your Full Name │
28+
└─────────────────────────────────────────────────────────┘
29+
```
30+
31+
---
32+
33+
## 📝 How to Add Your Real Name
34+
35+
### Step 1: Make Your Contribution
36+
Do something awesome:
37+
- Fix a bug 🐛
38+
- Add a feature ✨
39+
- Improve documentation 📝
40+
- Enhance UI/UX 🎨
41+
- Add tests ✅
42+
43+
### Step 2: Edit `contributors/contributor-names.json`
44+
45+
Open the file and find the `"contributors"` array. Add your entry:
46+
47+
```json
48+
{
49+
"contributors": [
50+
// ... existing entries ...
51+
{
52+
"github_username": "yourusername",
53+
"display_name": "Your Full Name"
54+
}
55+
]
56+
}
57+
```
58+
59+
**Real Example:**
60+
```json
61+
{
62+
"github_username": "fineanmol",
63+
"display_name": "Anmol Agarwal"
64+
}
65+
```
66+
67+
### Step 3: Submit Your PR
68+
69+
Include both:
70+
- ✅ Your actual code contribution
71+
- ✅ Your name entry in `contributor-names.json`
72+
73+
### Step 4: Wait for Magic ✨
74+
75+
Within **6 hours**, the automated system will:
76+
1. Fetch all contributors from GitHub API
77+
2. See your name in `contributor-names.json`
78+
3. Merge them together
79+
4. Update `contributorsList.js` automatically
80+
5. You appear with your real name!
81+
82+
---
83+
84+
## 🤔 Common Questions
85+
86+
### Q: Do I HAVE to add my real name?
87+
**A:** No! If you don't, you'll appear with your GitHub username. Both are fine!
88+
89+
### Q: Can I change my display name later?
90+
**A:** Yes! Just edit `contributor-names.json` again and submit a PR. It updates in 6 hours.
91+
92+
### Q: What if I want to use a nickname?
93+
**A:** Go for it! Use any name you want in the `display_name` field.
94+
95+
### Q: Will my contribution count if I don't add my name?
96+
**A:** Absolutely! The GitHub API tracks ALL contributors automatically.
97+
98+
### Q: Can I add my name before making a code contribution?
99+
**A:** Sure, but it won't show up until you actually contribute code/docs/etc.
100+
101+
### Q: What if there's a merge conflict?
102+
**A:** Very unlikely! `contributor-names.json` is sorted alphabetically, and it's much smaller than the old system. JSON merges much better than JavaScript arrays.
103+
104+
### Q: How often does the list update?
105+
**A:** Every 6 hours automatically. You can also manually trigger it from the Actions tab.
106+
107+
---
108+
109+
## 🔧 Technical Details
110+
111+
### The Workflow
112+
113+
```
114+
┌──────────────────────────────────────────────────────────┐
115+
│ 1. GitHub Actions Workflow (Every 6 hours) │
116+
│ ↓ │
117+
│ 2. Fetch contributors from GitHub API │
118+
│ ↓ │
119+
│ 3. Load contributor-names.json │
120+
│ ↓ │
121+
│ 4. Merge: API data + manual names │
122+
│ ↓ │
123+
│ 5. Generate contributorsList.js │
124+
│ ↓ │
125+
│ 6. Commit & push if changed │
126+
│ ↓ │
127+
│ 7. Website displays updated list! │
128+
└──────────────────────────────────────────────────────────┘
129+
```
130+
131+
### File Structure
132+
133+
```
134+
contributors/
135+
├── contributorsList.js ← AUTO-GENERATED (don't edit!)
136+
└── contributor-names.json ← EDIT THIS to add your name
137+
```
138+
139+
### What Gets Displayed?
140+
141+
```javascript
142+
// If you're in contributor-names.json:
143+
{
144+
fullname: "Anmol Agarwal", // ← Your display_name
145+
username: "https://github.com/fineanmol"
146+
}
147+
148+
// If you're NOT in contributor-names.json:
149+
{
150+
fullname: "fineanmol", // ← Your GitHub username
151+
username: "https://github.com/fineanmol"
152+
}
153+
```
154+
155+
---
156+
157+
## 🎯 Why This System?
158+
159+
### Old System (Manual)
160+
❌ Everyone edited `contributorsList.js` directly
161+
❌ 2695 lines of JavaScript
162+
❌ Merge conflicts everywhere
163+
❌ Hard to maintain
164+
165+
### New System (Hybrid)
166+
✅ GitHub API catches ALL contributors automatically
167+
✅ Small JSON file (432 entries) for names
168+
✅ Minimal merge conflicts
169+
✅ Easy to maintain
170+
✅ Best of both worlds!
171+
172+
---
173+
174+
## 📊 Examples
175+
176+
### Example 1: New Contributor (No Name Added)
177+
178+
**Your PR:** Fixed a bug in `main.js`
179+
180+
**Result on website:**
181+
```
182+
┌──────────────────────┐
183+
│ [Avatar Image] │
184+
│ @yourname │
185+
└──────────────────────┘
186+
```
187+
188+
### Example 2: New Contributor (With Name Added)
189+
190+
**Your PR:**
191+
1. Fixed a bug in `main.js`
192+
2. Added entry to `contributor-names.json`:
193+
```json
194+
{
195+
"github_username": "yourname",
196+
"display_name": "John Doe"
197+
}
198+
```
199+
200+
**Result on website:**
201+
```
202+
┌──────────────────────┐
203+
│ [Avatar Image] │
204+
│ John Doe │
205+
└──────────────────────┘
206+
```
207+
208+
---
209+
210+
## 🚀 Quick Start Template
211+
212+
Copy-paste this into `contributors/contributor-names.json`:
213+
214+
```json
215+
{
216+
"github_username": "REPLACE_WITH_YOUR_USERNAME",
217+
"display_name": "REPLACE WITH YOUR FULL NAME"
218+
}
219+
```
220+
221+
**Example:**
222+
```json
223+
{
224+
"github_username": "johndoe",
225+
"display_name": "John Doe"
226+
}
227+
```
228+
229+
---
230+
231+
## 💡 Pro Tips
232+
233+
1. **Keep it simple:** Just your name, no emojis or special formatting
234+
2. **Check spelling:** You'll be stuck with typos for 6 hours! 😅
235+
3. **Be patient:** Updates happen every 6 hours (or trigger manually from Actions tab)
236+
4. **One entry per person:** Don't add multiple entries for yourself
237+
5. **Sort alphabetically:** Helps avoid merge conflicts (script does this automatically)
238+
239+
---
240+
241+
## 🆘 Need Help?
242+
243+
- **File an issue:** [GitHub Issues](https://github.com/fineanmol/Hacktoberfest2025/issues)
244+
- **Check the docs:** [AUTOMATED-CONTRIBUTORS.md](./AUTOMATED-CONTRIBUTORS.md)
245+
- **Ask in PR comments:** We're here to help!
246+
247+
---
248+
249+
**Made with ❤️ for Hacktoberfest 2025**
250+

0 commit comments

Comments
 (0)