🤝 Contributing to OpenGrammar

Thank you for your interest in contributing to OpenGrammar! This guide will help you get started.

📋 Table of Contents

Ways to Contribute
Getting Started
Development Setup
Making Changes
Submitting Pull Requests
Code Style
Adding Grammar Rules
Documentation
Community

🎯 Ways to Contribute

Non-Developers

Everyone can contribute! You don't need to be a programmer:

Report Bugs
- Found something broken?
- Create a GitHub issue
- Describe what happened
Suggest Features
- Have an idea?
- Open a GitHub discussion
- Explain your use case
Improve Documentation
- Fix typos
- Clarify instructions
- Add examples
- Translate to other languages
Spread the Word
- Star the repository
- Share on social media
- Tell friends and colleagues
- Write blog posts

Developers

Code contributions welcome!

Fix Bugs
- Check "Issues" tab
- Look for "bug" label
- Submit fixes
Add Features
- Check "Roadmap"
- Look for "enhancement" label
- Implement and submit
Improve Performance
- Optimize code
- Reduce bundle size
- Improve loading times
Write Tests
- Add unit tests
- Integration tests
- E2E tests

🚀 Getting Started

Prerequisites

Required:

Node.js 18+ or Bun
Git
Code editor (VS Code recommended)

Nice to have:

Experience with TypeScript
Browser extension development knowledge
React familiarity

Quick Setup

# 1. Fork the repository
# Click "Fork" on GitHub

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/opengrammar.git
cd opengrammar

# 3. Add upstream remote
git remote add upstream https://github.com/swadhinbiswas/opengrammar.git

# 4. Install dependencies
cd opengrammar/opengrammar
bun install

# 5. Start development
bun run dev

💻 Development Setup

Project Structure

opengrammar/
├── backend/              # Serverless API
│   ├── src/
│   │   ├── index.ts     # Main API file
│   │   ├── analyzer.ts  # Grammar analyzer
│   │   └── analyzer-simple.ts  # Rule-based rules
│   ├── package.json
│   └── wrangler.toml
│
├── extension/            # Browser extension
│   ├── src/
│   │   ├── background/  # Service worker
│   │   ├── content/     # Content scripts
│   │   ├── popup/       # Popup UI
│   │   └── options/     # Settings page
│   ├── public/
│   ├── manifest.json
│   └── package.json
│
└── docs/                # Documentation

Development Commands

Backend

cd opengrammar/backend

# Install dependencies
bun install

# Start development server
bun run dev

# Type check
bun x tsc --noEmit

# Build for production
bun run build

# Deploy to Cloudflare
bun x wrangler deploy

Extension

cd opengrammar/extension

# Install dependencies
bun install

# Start development (watch mode)
bun run dev

# Build for production
bun run build

# Type check
bun x tsc --noEmit

Testing Your Changes

Build Extension
```
bun run build
```
Load in Browser
- Open chrome://extensions/
- Enable Developer Mode
- Click "Load unpacked"
- Select extension/dist folder
Test Features
- Type in text boxes
- Check grammar detection
- Test tone rewriting
- Verify settings save

🔧 Making Changes

Branch Naming

Use descriptive branch names:

feature/add-new-tone
fix/grammar-detection-bug
docs/update-readme
refactor/improve-performance

Commit Messages

Follow conventional commits:

feat: add persuasive tone option
fix: correct apostrophe detection
docs: update installation guide
refactor: optimize analyzer performance
test: add unit tests for rewrite API

Making Code Changes

Create Branch

git checkout -b feature/your-feature-name

Make Changes
- Edit files
- Add tests
- Update documentation

Test Locally

# Type check
bun x tsc --noEmit

# Build
bun run build

# Test in browser
# Load unpacked extension

Commit Changes

git add .
git commit -m "feat: add your feature"

📤 Submitting Pull Requests

Before Submitting

Checklist:

Code compiles without errors
Tests pass (if applicable)
Code is formatted
Documentation updated
Tested in browser
No console errors

Creating PR

Push to Your Fork

git push origin feature/your-feature-name

Open Pull Request
- Go to your fork on GitHub
- Click "Pull requests"
- Click "New pull request"
- Select your branch
- Compare to main branch

Fill Out Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Testing
Describe how you tested:
- [ ] Manual testing in browser
- [ ] Unit tests added/updated
- [ ] Tested on Chrome/Brave/Edge

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] No console errors
- [ ] Documentation updated

Submit PR
- Click "Create pull request"
- Wait for review
- Respond to feedback

PR Review Process

Automated Checks
- CI/CD runs tests
- Type checking
- Build verification
Maintainer Review
- Code quality check
- Functionality verification
- Security review
Feedback & Changes
- Respond to comments
- Make requested changes
- Push updates to branch
Merge
- PR approved
- All checks pass
- Merged to main

📝 Code Style

TypeScript

General Guidelines:

// Use interfaces for types
interface GrammarIssue {
  type: 'grammar' | 'spelling' | 'style';
  original: string;
  suggestion: string;
  reason: string;
}

// Use arrow functions
const analyze = (text: string): GrammarIssue[] => {
  // Implementation
};

// Use template literals
const message = `Found ${issues.length} issues`;

// Use optional chaining
const length = text?.length ?? 0;

Naming Conventions:

// Variables: camelCase
const grammarRules = [];

// Functions: camelCase
function analyzeText() {}

// Classes: PascalCase
class GrammarAnalyzer {}

// Interfaces: PascalCase
interface AnalyzerConfig {}

// Constants: UPPER_SNAKE_CASE
const MAX_TEXT_LENGTH = 50000;

React/JSX

Component Structure:

import React, { useState, useEffect } from 'react';

interface Props {
  title: string;
  onSave: (data: any) => void;
}

export const MyComponent: React.FC<Props> = ({ title, onSave }) => {
  const [state, setState] = useState('');
  
  return (
    <div className="container">
      <h1>{title}</h1>
    </div>
  );
};

CSS Classes:

// Use Tailwind CSS classes
<div className="flex items-center gap-2 p-4 bg-white rounded-lg shadow">
  Content
</div>

📚 Adding Grammar Rules

Where Rules Live

Rules are in backend/src/analyzer-simple.ts

Rule Structure

{
  pattern: /\bteh\b/gi,
  suggestion: 'the',
  reason: 'Misspelled word. The correct spelling is "the".',
  type: 'spelling',
  severity: 'error'
}

Adding a New Rule

Example: Add "alot" → "a lot"

// In analyzer-simple.ts
checkCommonMisspellings(text: string): GrammarIssue[] {
  const issues: GrammarIssue[] = [];
  
  const rules = [
    {
      pattern: /\balot\b/gi,
      suggestion: 'a lot',
      reason: '"Alot" is not a word. Use "a lot" (two words).',
      type: 'spelling',
      severity: 'error'
    },
    // Add more rules here
  ];
  
  // Rule checking logic
  return issues;
}

Testing Rules

// Test the rule
const text = "I have alot of work";
const issues = checkCommonMisspellings(text);
console.log(issues); // Should detect "alot"

Rule Categories

1. Spelling

{
  pattern: /\brecieve\b/gi,
  suggestion: 'receive',
  reason: 'Misspelled word',
  type: 'spelling'
}

2. Grammar

{
  pattern: /\bme and [a-z]+\b/gi,
  suggestion: 'I and [name]',
  reason: 'Use subject pronoun',
  type: 'grammar'
}

3. Style

{
  pattern: /\bvery good\b/gi,
  suggestion: 'excellent',
  reason: 'Consider a stronger word',
  type: 'style'
}

4. Clarity

{
  pattern: /.{35,}/g,  // Sentences > 35 chars
  suggestion: 'Shorten sentence',
  reason: 'Sentence may be hard to read',
  type: 'clarity'
}

📖 Documentation

Documentation Structure

docs/
├── 00-index.md           # Documentation index
├── 01-quick-start.md     # Quick start guide
├── 04-browser-extension-setup.md
├── 05-backend-deployment.md
├── 06-docker-self-hosting.md
├── 07-ai-providers.md
├── 09-using-opengrammar.md
├── 10-tone-rewriting.md
├── 11-writing-statistics.md
├── 12-keyboard-shortcuts.md
├── 15-api-reference.md
├── 18-troubleshooting.md
├── 19-faq.md
└── 21-contributing.md    # This file

Documentation Guidelines

Writing Style:

Clear and concise
Use active voice
Include examples
Add screenshots when helpful

Markdown Format:

# H1 Heading
## H2 Heading
### H3 Heading

**Bold** for emphasis
`Code` for commands/paths
> Blockquotes for notes

- Bullet lists
1. Numbered lists

[Links](url)
![Images](url)

Code Blocks:

```bash
# Bash commands
npm install
```

```typescript
// TypeScript code
const value = 42;
```

```json
// JSON examples
{
  "key": "value"
}
```

🌟 Community

Communication Channels

GitHub:

Issues - Bug reports
Discussions - Questions
Pull Requests - Code contributions

Discord: (if available)

Join server link
Introduce yourself
Ask questions in #help channel

Code of Conduct

Be respectful:

Welcome all contributors
No harassment
Constructive feedback
Inclusive language

Report issues:

Contact maintainers
Use private channels for sensitive issues

Recognition

Contributors get:

Credit in README
Contributor badge
Shout-outs in releases
Community recognition

🎓 Learning Resources

Getting Help

Stuck?

Check existing issues
Search documentation
Ask in discussions
Contact maintainers

Want to pair program?

Reach out to maintainers
Join community calls
Participate in hackathons

🏆 Contributor Recognition

Contributor Levels

First Contribution:

Welcome message
Contributor badge
Merged PR

Regular Contributor (5+ PRs):

Featured in release notes
Contributor spotlight
Direct input on features

Core Contributor (20+ PRs):

Write access to repository
Vote on major decisions
Represent project

Hall of Fame

Top contributors featured in:

README.md
Release notes
Project website
Conference talks

📞 Contact Maintainers

For questions:

GitHub Discussions
Discord server
Email (if listed)

For sensitive issues:

Private message maintainers
Email security contact
Report vulnerabilities privately

Thank you for contributing to OpenGrammar! 🎉

Your contributions make OpenGrammar better for everyone!