swadhin / opengrammar public

swadhinbiswas

[email protected]
2026-03-14 19:16:50 +0600 committed NaN years ago
12b0f69
commit 12b0f69
1 file changed
+688 -0
Showing 1 changed file+688-0
docs/21-contributing.md
▼docs/21-contributing.md
+688-0
@@ -0,0 +1,688 @@
1
+# 🤝 Contributing to OpenGrammar
2
+
3
+Thank you for your interest in contributing to OpenGrammar! This guide will help you get started.
4
+
5
+---
6
+
7
+## 📋 Table of Contents
8
+
9
+1. [Ways to Contribute](#ways-to-contribute)
10
+2. [Getting Started](#getting-started)
11
+3. [Development Setup](#development-setup)
12
+4. [Making Changes](#making-changes)
13
+5. [Submitting Pull Requests](#submitting-pull-requests)
14
+6. [Code Style](#code-style)
15
+7. [Adding Grammar Rules](#adding-grammar-rules)
16
+8. [Documentation](#documentation)
17
+9. [Community](#community)
18
+
19
+---
20
+
21
+## 🎯 Ways to Contribute
22
+
23
+### Non-Developers
24
+
25
+**Everyone can contribute!** You don't need to be a programmer:
26
+
27
+1. **Report Bugs**
28
+ - Found something broken?
29
+ - Create a GitHub issue
30
+ - Describe what happened
31
+
32
+2. **Suggest Features**
33
+ - Have an idea?
34
+ - Open a GitHub discussion
35
+ - Explain your use case
36
+
37
+3. **Improve Documentation**
38
+ - Fix typos
39
+ - Clarify instructions
40
+ - Add examples
41
+ - Translate to other languages
42
+
43
+4. **Spread the Word**
44
+ - Star the repository
45
+ - Share on social media
46
+ - Tell friends and colleagues
47
+ - Write blog posts
48
+
49
+### Developers
50
+
51
+**Code contributions welcome!**
52
+
53
+1. **Fix Bugs**
54
+ - Check "Issues" tab
55
+ - Look for "bug" label
56
+ - Submit fixes
57
+
58
+2. **Add Features**
59
+ - Check "Roadmap"
60
+ - Look for "enhancement" label
61
+ - Implement and submit
62
+
63
+3. **Improve Performance**
64
+ - Optimize code
65
+ - Reduce bundle size
66
+ - Improve loading times
67
+
68
+4. **Write Tests**
69
+ - Add unit tests
70
+ - Integration tests
71
+ - E2E tests
72
+
73
+---
74
+
75
+## 🚀 Getting Started
76
+
77
+### Prerequisites
78
+
79
+**Required:**
80
+- Node.js 18+ or Bun
81
+- Git
82
+- Code editor (VS Code recommended)
83
+
84
+**Nice to have:**
85
+- Experience with TypeScript
86
+- Browser extension development knowledge
87
+- React familiarity
88
+
89
+### Quick Setup
90
+
91
+```bash
92
+# 1. Fork the repository
93
+# Click "Fork" on GitHub
94
+
95
+# 2. Clone your fork
96
+git clone https://github.com/YOUR_USERNAME/opengrammar.git
97
+cd opengrammar
98
+
99
+# 3. Add upstream remote
100
+git remote add upstream https://github.com/swadhinbiswas/opengrammar.git
101
+
102
+# 4. Install dependencies
103
+cd opengrammar/opengrammar
104
+bun install
105
+
106
+# 5. Start development
107
+bun run dev
108
+```
109
+
110
+---
111
+
112
+## 💻 Development Setup
113
+
114
+### Project Structure
115
+
116
+```
117
+opengrammar/
118
+├── backend/ # Serverless API
119
+│ ├── src/
120
+│ │ ├── index.ts # Main API file
121
+│ │ ├── analyzer.ts # Grammar analyzer
122
+│ │ └── analyzer-simple.ts # Rule-based rules
123
+│ ├── package.json
124
+│ └── wrangler.toml
125
+│
126
+├── extension/ # Browser extension
127
+│ ├── src/
128
+│ │ ├── background/ # Service worker
129
+│ │ ├── content/ # Content scripts
130
+│ │ ├── popup/ # Popup UI
131
+│ │ └── options/ # Settings page
132
+│ ├── public/
133
+│ ├── manifest.json
134
+│ └── package.json
135
+│
136
+└── docs/ # Documentation
137
+```
138
+
139
+### Development Commands
140
+
141
+#### Backend
142
+
143
+```bash
144
+cd opengrammar/backend
145
+
146
+# Install dependencies
147
+bun install
148
+
149
+# Start development server
150
+bun run dev
151
+
152
+# Type check
153
+bun x tsc --noEmit
154
+
155
+# Build for production
156
+bun run build
157
+
158
+# Deploy to Cloudflare
159
+bun x wrangler deploy
160
+```
161
+
162
+#### Extension
163
+
164
+```bash
165
+cd opengrammar/extension
166
+
167
+# Install dependencies
168
+bun install
169
+
170
+# Start development (watch mode)
171
+bun run dev
172
+
173
+# Build for production
174
+bun run build
175
+
176
+# Type check
177
+bun x tsc --noEmit
178
+```
179
+
180
+### Testing Your Changes
181
+
182
+1. **Build Extension**
183
+ ```bash
184
+ bun run build
185
+ ```
186
+
187
+2. **Load in Browser**
188
+ - Open `chrome://extensions/`
189
+ - Enable Developer Mode
190
+ - Click "Load unpacked"
191
+ - Select `extension/dist` folder
192
+
193
+3. **Test Features**
194
+ - Type in text boxes
195
+ - Check grammar detection
196
+ - Test tone rewriting
197
+ - Verify settings save
198
+
199
+---
200
+
201
+## 🔧 Making Changes
202
+
203
+### Branch Naming
204
+
205
+Use descriptive branch names:
206
+```
207
+feature/add-new-tone
208
+fix/grammar-detection-bug
209
+docs/update-readme
210
+refactor/improve-performance
211
+```
212
+
213
+### Commit Messages
214
+
215
+Follow conventional commits:
216
+```
217
+feat: add persuasive tone option
218
+fix: correct apostrophe detection
219
+docs: update installation guide
220
+refactor: optimize analyzer performance
221
+test: add unit tests for rewrite API
222
+```
223
+
224
+### Making Code Changes
225
+
226
+1. **Create Branch**
227
+ ```bash
228
+ git checkout -b feature/your-feature-name
229
+ ```
230
+
231
+2. **Make Changes**
232
+ - Edit files
233
+ - Add tests
234
+ - Update documentation
235
+
236
+3. **Test Locally**
237
+ ```bash
238
+ # Type check
239
+ bun x tsc --noEmit
240
+
241
+ # Build
242
+ bun run build
243
+
244
+ # Test in browser
245
+ # Load unpacked extension
246
+ ```
247
+
248
+4. **Commit Changes**
249
+ ```bash
250
+ git add .
251
+ git commit -m "feat: add your feature"
252
+ ```
253
+
254
+---
255
+
256
+## 📤 Submitting Pull Requests
257
+
258
+### Before Submitting
259
+
260
+**Checklist:**
261
+- [ ] Code compiles without errors
262
+- [ ] Tests pass (if applicable)
263
+- [ ] Code is formatted
264
+- [ ] Documentation updated
265
+- [ ] Tested in browser
266
+- [ ] No console errors
267
+
268
+### Creating PR
269
+
270
+1. **Push to Your Fork**
271
+ ```bash
272
+ git push origin feature/your-feature-name
273
+ ```
274
+
275
+2. **Open Pull Request**
276
+ - Go to your fork on GitHub
277
+ - Click "Pull requests"
278
+ - Click "New pull request"
279
+ - Select your branch
280
+ - Compare to `main` branch
281
+
282
+3. **Fill Out Template**
283
+ ```markdown
284
+ ## Description
285
+ Brief description of changes
286
+
287
+ ## Type of Change
288
+ - [ ] Bug fix
289
+ - [ ] New feature
290
+ - [ ] Documentation update
291
+ - [ ] Performance improvement
292
+
293
+ ## Testing
294
+ Describe how you tested:
295
+ - [ ] Manual testing in browser
296
+ - [ ] Unit tests added/updated
297
+ - [ ] Tested on Chrome/Brave/Edge
298
+
299
+ ## Checklist
300
+ - [ ] Code follows style guidelines
301
+ - [ ] Self-review completed
302
+ - [ ] No console errors
303
+ - [ ] Documentation updated
304
+ ```
305
+
306
+4. **Submit PR**
307
+ - Click "Create pull request"
308
+ - Wait for review
309
+ - Respond to feedback
310
+
311
+### PR Review Process
312
+
313
+1. **Automated Checks**
314
+ - CI/CD runs tests
315
+ - Type checking
316
+ - Build verification
317
+
318
+2. **Maintainer Review**
319
+ - Code quality check
320
+ - Functionality verification
321
+ - Security review
322
+
323
+3. **Feedback & Changes**
324
+ - Respond to comments
325
+ - Make requested changes
326
+ - Push updates to branch
327
+
328
+4. **Merge**
329
+ - PR approved
330
+ - All checks pass
331
+ - Merged to main
332
+
333
+---
334
+
335
+## 📝 Code Style
336
+
337
+### TypeScript
338
+
339
+**General Guidelines:**
340
+```typescript
341
+// Use interfaces for types
342
+interface GrammarIssue {
343
+ type: 'grammar' | 'spelling' | 'style';
344
+ original: string;
345
+ suggestion: string;
346
+ reason: string;
347
+}
348
+
349
+// Use arrow functions
350
+const analyze = (text: string): GrammarIssue[] => {
351
+ // Implementation
352
+};
353
+
354
+// Use template literals
355
+const message = `Found ${issues.length} issues`;
356
+
357
+// Use optional chaining
358
+const length = text?.length ?? 0;
359
+```
360
+
361
+**Naming Conventions:**
362
+```typescript
363
+// Variables: camelCase
364
+const grammarRules = [];
365
+
366
+// Functions: camelCase
367
+function analyzeText() {}
368
+
369
+// Classes: PascalCase
370
+class GrammarAnalyzer {}
371
+
372
+// Interfaces: PascalCase
373
+interface AnalyzerConfig {}
374
+
375
+// Constants: UPPER_SNAKE_CASE
376
+const MAX_TEXT_LENGTH = 50000;
377
+```
378
+
379
+### React/JSX
380
+
381
+**Component Structure:**
382
+```typescript
383
+import React, { useState, useEffect } from 'react';
384
+
385
+interface Props {
386
+ title: string;
387
+ onSave: (data: any) => void;
388
+}
389
+
390
+export const MyComponent: React.FC<Props> = ({ title, onSave }) => {
391
+ const [state, setState] = useState('');
392
+
393
+ return (
394
+ <div className="container">
395
+ <h1>{title}</h1>
396
+ </div>
397
+ );
398
+};
399
+```
400
+
401
+**CSS Classes:**
402
+```typescript
403
+// Use Tailwind CSS classes
404
+<div className="flex items-center gap-2 p-4 bg-white rounded-lg shadow">
405
+ Content
406
+</div>
407
+```
408
+
409
+---
410
+
411
+## 📚 Adding Grammar Rules
412
+
413
+### Where Rules Live
414
+
415
+Rules are in `backend/src/analyzer-simple.ts`
416
+
417
+### Rule Structure
418
+
419
+```typescript
420
+{
421
+ pattern: /\bteh\b/gi,
422
+ suggestion: 'the',
423
+ reason: 'Misspelled word. The correct spelling is "the".',
424
+ type: 'spelling',
425
+ severity: 'error'
426
+}
427
+```
428
+
429
+### Adding a New Rule
430
+
431
+**Example: Add "alot" → "a lot"**
432
+
433
+```typescript
434
+// In analyzer-simple.ts
435
+checkCommonMisspellings(text: string): GrammarIssue[] {
436
+ const issues: GrammarIssue[] = [];
437
+
438
+ const rules = [
439
+ {
440
+ pattern: /\balot\b/gi,
441
+ suggestion: 'a lot',
442
+ reason: '"Alot" is not a word. Use "a lot" (two words).',
443
+ type: 'spelling',
444
+ severity: 'error'
445
+ },
446
+ // Add more rules here
447
+ ];
448
+
449
+ // Rule checking logic
450
+ return issues;
451
+}
452
+```
453
+
454
+### Testing Rules
455
+
456
+```typescript
457
+// Test the rule
458
+const text = "I have alot of work";
459
+const issues = checkCommonMisspellings(text);
460
+console.log(issues); // Should detect "alot"
461
+```
462
+
463
+### Rule Categories
464
+
465
+**1. Spelling**
466
+```typescript
467
+{
468
+ pattern: /\brecieve\b/gi,
469
+ suggestion: 'receive',
470
+ reason: 'Misspelled word',
471
+ type: 'spelling'
472
+}
473
+```
474
+
475
+**2. Grammar**
476
+```typescript
477
+{
478
+ pattern: /\bme and [a-z]+\b/gi,
479
+ suggestion: 'I and [name]',
480
+ reason: 'Use subject pronoun',
481
+ type: 'grammar'
482
+}
483
+```
484
+
485
+**3. Style**
486
+```typescript
487
+{
488
+ pattern: /\bvery good\b/gi,
489
+ suggestion: 'excellent',
490
+ reason: 'Consider a stronger word',
491
+ type: 'style'
492
+}
493
+```
494
+
495
+**4. Clarity**
496
+```typescript
497
+{
498
+ pattern: /.{35,}/g, // Sentences > 35 chars
499
+ suggestion: 'Shorten sentence',
500
+ reason: 'Sentence may be hard to read',
501
+ type: 'clarity'
502
+}
503
+```
504
+
505
+---
506
+
507
+## 📖 Documentation
508
+
509
+### Documentation Structure
510
+
511
+```
512
+docs/
513
+├── 00-index.md # Documentation index
514
+├── 01-quick-start.md # Quick start guide
515
+├── 04-browser-extension-setup.md
516
+├── 05-backend-deployment.md
517
+├── 06-docker-self-hosting.md
518
+├── 07-ai-providers.md
519
+├── 09-using-opengrammar.md
520
+├── 10-tone-rewriting.md
521
+├── 11-writing-statistics.md
522
+├── 12-keyboard-shortcuts.md
523
+├── 15-api-reference.md
524
+├── 18-troubleshooting.md
525
+├── 19-faq.md
526
+└── 21-contributing.md # This file
527
+```
528
+
529
+### Documentation Guidelines
530
+
531
+**Writing Style:**
532
+- Clear and concise
533
+- Use active voice
534
+- Include examples
535
+- Add screenshots when helpful
536
+
537
+**Markdown Format:**
538
+```markdown
539
+# H1 Heading
540
+## H2 Heading
541
+### H3 Heading
542
+
543
+**Bold** for emphasis
544
+`Code` for commands/paths
545
+> Blockquotes for notes
546
+
547
+- Bullet lists
548
+1. Numbered lists
549
+
550
+[Links](url)
551
+![Images](url)
552
+```
553
+
554
+**Code Blocks:**
555
+````markdown
556
+```bash
557
+# Bash commands
558
+npm install
559
+```
560
+
561
+```typescript
562
+// TypeScript code
563
+const value = 42;
564
+```
565
+
566
+```json
567
+// JSON examples
568
+{
569
+ "key": "value"
570
+}
571
+```
572
+````
573
+
574
+---
575
+
576
+## 🌟 Community
577
+
578
+### Communication Channels
579
+
580
+**GitHub:**
581
+- [Issues](https://github.com/swadhinbiswas/opengrammar/issues) - Bug reports
582
+- [Discussions](https://github.com/swadhinbiswas/opengrammar/discussions) - Questions
583
+- [Pull Requests](https://github.com/swadhinbiswas/opengrammar/pulls) - Code contributions
584
+
585
+**Discord:** (if available)
586
+- Join server link
587
+- Introduce yourself
588
+- Ask questions in #help channel
589
+
590
+### Code of Conduct
591
+
592
+**Be respectful:**
593
+- Welcome all contributors
594
+- No harassment
595
+- Constructive feedback
596
+- Inclusive language
597
+
598
+**Report issues:**
599
+- Contact maintainers
600
+- Use private channels for sensitive issues
601
+
602
+### Recognition
603
+
604
+**Contributors get:**
605
+- Credit in README
606
+- Contributor badge
607
+- Shout-outs in releases
608
+- Community recognition
609
+
610
+---
611
+
612
+## 🎓 Learning Resources
613
+
614
+### Recommended Reading
615
+
616
+**Browser Extensions:**
617
+- [Chrome Extensions Docs](https://developer.chrome.com/docs/extensions/)
618
+- [Manifest V3 Guide](https://developer.chrome.com/docs/extensions/mv3/intro/)
619
+
620
+**TypeScript:**
621
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
622
+- [TypeScript Deep Dive](https://basarat.gitbook.io/typescript/)
623
+
624
+**React:**
625
+- [React Docs](https://react.dev/)
626
+- [React Patterns](https://reactpatterns.com/)
627
+
628
+### Getting Help
629
+
630
+**Stuck?**
631
+1. Check existing issues
632
+2. Search documentation
633
+3. Ask in discussions
634
+4. Contact maintainers
635
+
636
+**Want to pair program?**
637
+- Reach out to maintainers
638
+- Join community calls
639
+- Participate in hackathons
640
+
641
+---
642
+
643
+## 🏆 Contributor Recognition
644
+
645
+### Contributor Levels
646
+
647
+**First Contribution:**
648
+- Welcome message
649
+- Contributor badge
650
+- Merged PR
651
+
652
+**Regular Contributor (5+ PRs):**
653
+- Featured in release notes
654
+- Contributor spotlight
655
+- Direct input on features
656
+
657
+**Core Contributor (20+ PRs):**
658
+- Write access to repository
659
+- Vote on major decisions
660
+- Represent project
661
+
662
+### Hall of Fame
663
+
664
+Top contributors featured in:
665
+- README.md
666
+- Release notes
667
+- Project website
668
+- Conference talks
669
+
670
+---
671
+
672
+## 📞 Contact Maintainers
673
+
674
+**For questions:**
675
+- GitHub Discussions
676
+- Discord server
677
+- Email (if listed)
678
+
679
+**For sensitive issues:**
680
+- Private message maintainers
681
+- Email security contact
682
+- Report vulnerabilities privately
683
+
684
+---
685
+
686
+**Thank you for contributing to OpenGrammar! 🎉**
687
+
688
+Your contributions make OpenGrammar better for everyone!
0
689