Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
693 lines (491 loc) · 16 KB

CONTRIBUTING.md

File metadata and controls

693 lines (491 loc) · 16 KB
Raw

🤝 Contributing to LinguaLive

Thank you for your interest in contributing to LinguaLive! This document provides guidelines and instructions to help you contribute effectively to our project. Whether you're fixing bugs, adding features, or improving documentation, we appreciate your help! 💪

📋 Table of Contents

💖 Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please follow these principles:

  • ✨ Be respectful — Treat everyone with kindness and respect
  • 🤝 Be collaborative — Help others and accept feedback gracefully
  • 🎯 Be constructive — Provide helpful feedback and solutions, not criticism
  • 🔒 Be inclusive — Welcome people of all backgrounds and experience levels
  • 🚫 No harassment — Any form of harassment, discrimination, or abuse will not be tolerated

🌟 Ways to Contribute

🐛 Report Bugs

Found a bug? Help us squash it! Create a bug report.

✨ Request Features

Have an idea? Submit a feature request in the Discussions tab.

🔧 Fix Bugs

Pick an issue labeled bug and submit a pull request with your fix.

🎨 Add Features

Browse open issues labeled enhancement or implement something from our roadmap.

📚 Improve Documentation

Help us write better docs, examples, and guides.

🧪 Write Tests

Increase our test coverage and ensure code quality.

💭 Review PRs

Peer review is valuable! Comment on open pull requests.

🚀 Getting Started

1. Fork the Repository

Click the Fork button on GitHub to create your own copy.

# Clone your fork
git clone https://github.com/hardikrathod777/lingualive-ai-language-coach.git
cd lingualive-ai-language-coach

2. Add Upstream Remote

Keep your fork in sync with the main repository.

git remote add upstream https://github.com/original-owner/lingualive-ai-language-coach.git

3. Create a Feature Branch

Always work on a new branch, never on main.

git checkout -b feature/your-feature-name

See Branch Naming Conventions for guidance.

4. Make Your Changes

Edit files, add features, or fix bugs. See Development Setup.

5. Commit Your Changes

Follow our Commit Guidelines.

git commit -m "feat: add amazing feature"

6. Push to Your Fork

git push origin feature/your-feature-name

7. Create a Pull Request

Submit your PR with a clear description. See Pull Request Process.

🛠️ Development Setup

Prerequisites

  • Node.js 18 or higher
  • npm or yarn package manager
  • Git for version control
  • Google Gemini API Key (Get one free)

Installation Steps

  1. Install dependencies

    npm install

  2. Set up environment variables

    cp .env.example .env.local

    Edit .env.local and add your API key:

    NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here

  3. Start the development server

    npm run dev

    The app will be available at http://localhost:3000

  4. Run linting

    npm run lint

Development Commands

Command Description
npm run dev Start development server
npm run build Build for production
npm run start Start production server
npm run lint Run ESLint on all files
npm run clean Clean build artifacts

📝 Commit Guidelines

Write clear, descriptive commit messages that explain what and why, not just what.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Type

Must be one of the following:

  • feat — A new feature
  • fix — A bug fix
  • docs — Documentation only changes
  • style — Changes that don't affect code meaning (formatting, whitespace, etc.)
  • refactor — Code change that neither fixes a bug nor adds a feature
  • perf — Code change that improves performance
  • test — Adding or updating tests
  • chore — Changes to build process, dependencies, or tooling
  • ci — Changes to CI configuration files

Scope

Optional. The area of the codebase affected:

  • components
  • hooks
  • lib
  • audio
  • ui
  • docs
  • ci

Subject

  • Use imperative mood ("add feature" not "added feature")
  • Don't capitalize the first letter
  • No period (.) at the end
  • Limit to 50 characters or less
  • Be specific and descriptive

Body

Optional but recommended:

  • Explain what and why, not how
  • Wrap at 72 characters
  • Reference issues with Closes #123
  • Separate from subject with blank line

Examples

Good:

feat(components): add language difficulty selector

The new selector allows users to choose between beginner, 
intermediate, and advanced conversation modes. This helps 
tailor the AI responses to the user's proficiency level.

Closes #456

Also good:

fix(audio): prevent audio feedback loop on reconnect

Clear the audio player buffer before starting a new session
to prevent overlapping audio playback.

Avoid:

updated stuff
fixed thing
ADDED NEW FEATURE

🌿 Branch Naming Conventions

Use the following format for branch names:

<type>/<description>

Types

  • feature/ — New features
  • fix/ — Bug fixes
  • docs/ — Documentation updates
  • refactor/ — Code refactoring
  • test/ — Test additions or modifications
  • chore/ — Build, dependencies, tooling
  • perf/ — Performance improvements

Examples

# Good branch names
git checkout -b feature/add-difficulty-levels
git checkout -b fix/audio-feedback-loop
git checkout -b docs/update-setup-guide
git checkout -b refactor/audio-utils
git checkout -b test/add-language-selector-tests

# Avoid these
git checkout -b my-changes
git checkout -b fix-stuff
git checkout -b test123

🔄 Pull Request Process

Before Opening a PR

  • Create a branch from main
  • Make your changes
  • Run linting: npm run lint
  • Test thoroughly in development
  • Commit with clear messages following our guidelines
  • Push to your fork
  • Verify all changes are present

Opening the PR

  1. Go to GitHub and open a new pull request
  2. Set the base branch to main
  3. Use the PR template (auto-filled when you open the PR)
  4. Link related issues using Closes #NUMBER

PR Title Format

Use the same format as commit messages:

feat: add language difficulty selector
fix: resolve audio feedback loop on reconnect
docs: update setup instructions

PR Description Template

## 📋 Description
Brief description of what this PR does and why.

## 🎯 Related Issue
Closes #NUMBER (if applicable)

## 🔍 Type of Change
- [ ] 🐛 Bug fix
- [ ] ✨ New feature
- [ ] 📚 Documentation update
- [ ] 🔄 Refactoring
- [ ] ⚡ Performance improvement
- [ ] 🧪 Test addition/update

## 📝 Changes Made
- Change 1
- Change 2
- Change 3

## ✅ Testing
- [ ] Tested in development environment
- [ ] No console errors or warnings
- [ ] Linting passes (`npm run lint`)
- [ ] Changes work as intended

## 📸 Screenshots/Demo
(If applicable, add before/after screenshots or demo links)

## 🎓 Learning Notes
(Any important context or decisions made)

Review Process

  • 👀 At least one reviewer will review your PR
  • 💬 Address feedback constructively
  • 🔄 Push updates to the same branch (no new PR needed)
  • ✅ Once approved, maintainers will merge

🧪 Testing Guidelines

Writing Tests

We encourage contributions that include tests! Here's how:

  1. Create test files alongside source files

    components/
├── LanguagePartner.tsx
└── LanguagePartner.test.tsx

  2. Use descriptive test names

    describe('LanguagePartner', () => {
  it('should initialize with English as default language', () => {
    // test code
  });
  
  it('should handle language change correctly', () => {
    // test code
  });
});

  3. Test edge cases and error scenarios

  4. Keep tests focused — one concept per test

Running Tests

npm test
npm test -- --watch    # Watch mode
npm test -- --coverage # Coverage report

Coverage Goals

  • Aim for >80% code coverage for new features
  • Maintain or improve existing coverage
  • All public APIs should be tested

🎨 Code Style & Linting

Running ESLint

npm run lint              # Check all files
npm run lint --fix       # Auto-fix issues
npm run lint app/        # Check specific folder

Code Style Standards

  • Format: Follow ESLint configuration in .eslintrc.json
  • TypeScript: Use strict typing, avoid any
  • Naming: Use camelCase for variables/functions, PascalCase for components/classes
  • Imports: Organize imports alphabetically, group by type
  • Comments: Write clear, concise comments explaining "why", not "what"

Example

// Good: Type-safe, clear naming, logical organization
import { useState, useRef } from 'react';
import { GoogleGenAI } from '@google/genai';

interface AudioConfig {
  sampleRate: number;
  channelCount: number;
}

export function useAudioRecorder(config: AudioConfig) {
  const [isRecording, setIsRecording] = useState(false);
  
  // Implementation...
}

Pre-commit Hooks

We recommend setting up husky for automatic linting before commits:

npm install husky --save-dev
npx husky install

📚 Documentation

When to Update Docs

  • 📝 New features should include documentation
  • 🔄 Breaking changes require doc updates
  • 🐛 Bug fixes might need clarification
  • 💡 Complex logic deserves explanation

Documentation Standards

  • README.md — High-level overview and quick start
  • CONTRIBUTING.md — This file! Contribution guidelines
  • Code comments — Explain complex logic, not obvious code
  • Commit messages — Explain context and reasoning
  • PR descriptions — Describe changes and impact

JSDoc Comments

/**
 * Records audio from the user's microphone
 * @param {AudioConfig} config - Audio recording configuration
 * @returns {Promise<AudioData>} The recorded audio data
 * @throws {Error} If microphone access is denied
 */
export async function recordAudio(config: AudioConfig): Promise<AudioData> {
  // implementation
}

🐛 Reporting Issues

Before Creating an Issue

  • ✅ Search existing issues to avoid duplicates
  • ✅ Check the FAQ and troubleshooting sections
  • ✅ Verify the issue is in the latest version
  • ✅ Test in multiple browsers/environments

Bug Report Template

## 🐛 Bug Description
A clear description of the bug.

## 📍 Reproduction Steps
1. Step 1
2. Step 2
3. Step 3

## 🤔 Expected Behavior
What should happen

## 👀 Actual Behavior
What actually happens

## 💻 Environment
- OS: Windows/macOS/Linux
- Browser: Chrome/Firefox/Safari
- Node version: (if applicable)
- npm version: (if applicable)

## 🖼️ Screenshots
(If applicable)

## 📝 Additional Context
Any other relevant information

Feature Request Template

## ✨ Feature Description
Clear description of the feature you want

## 🎯 Use Case
Why do you need this? What problem does it solve?

## 📋 Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## 🔗 Related
Links to related issues or discussions

💬 Asking for Help

Finding Help

Good Help Questions Include

  • ✅ Clear description of what you're trying to do
  • ✅ Steps you've already tried
  • ✅ Error messages or code snippets
  • ✅ Environment details (OS, Node version, etc.)
  • ✅ Links to related issues or docs

🎓 Learning Resources

Project Architecture

Code Navigation

  • Entry Point: app/layout.tsx and app/page.tsx
  • Main Component: components/LanguagePartner.tsx
  • Audio Logic: lib/audio-utils.ts
  • Utilities: lib/utils.ts

Key Concepts

  • 🎤 Audio Recording — Understanding Web Audio API
  • 🌐 Multi-Language Support — How language switching works
  • 🔄 State Management — React hooks for session state
  • 🎨 Styling — Tailwind CSS patterns used in the project

✅ Checklist Before Submitting PR

  • I've read the Code of Conduct
  • I've created a feature branch (not on main)
  • I've followed the commit message guidelines
  • I've run npm run lint and fixed issues
  • I've tested my changes locally
  • I've updated documentation if needed
  • I've linked related issues with Closes #NUMBER
  • I've filled out the PR template completely
  • I've requested a review from maintainers

🚀 Merging & After

Maintainers Will

  • ✅ Review your PR thoroughly
  • ✅ Test the changes
  • ✅ Merge once approved
  • ✅ Close related issues automatically
  • ✅ Add you to contributors list

You Can

  • 🎉 Celebrate your contribution!
  • 📢 Share your work with the community
  • 🔄 Continue contributing to other issues
  • 📚 Help review other PRs

📊 Contribution Levels

🌱 Beginner-Friendly

Start with these if you're new to the project:

  • Documentation improvements
  • Bug fixes with clear reproduction steps
  • Test additions
  • Code comment improvements

Filter by label: good-first-issue, documentation, help-wanted

🌿 Intermediate

Once you're familiar with the codebase:

  • New features from the roadmap
  • Refactoring tasks
  • Performance improvements
  • Complex bug fixes

Filter by label: enhancement, refactor

🌳 Advanced

For experienced contributors:

  • Architecture decisions
  • Major refactors
  • Multi-component features
  • Performance optimization

Discuss with maintainers in Issues/Discussions first

🎊 Recognition

Contributors Hall of Fame

All contributors are recognized in:

Thank you for being part of our community! 💝

📞 Questions?

Don't hesitate to ask! Use any of these channels:

  • 🐙 GitHub Issues — For bugs and feature requests
  • 💬 GitHub Discussions — For questions and ideas
  • 📧 Email — support@lingualive.dev
  • 🎯 Discord — Real-time chat with the community

📜 License

By contributing to LinguaLive, you agree that your contributions will be licensed under its MIT License.

🙌 Thank You!

Your contributions make LinguaLive better for everyone.

🚀 Get Started • 📖 View Roadmap • ⭐ Star us on GitHub

Happy coding! 💻✨