Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
196 lines (145 loc) · 5.21 KB

CONTRIBUTING.md

File metadata and controls

196 lines (145 loc) · 5.21 KB

Contributing to Language Learning Node

Thank you for your interest in contributing to the Language Learning App! This document provides guidelines and instructions for contributing.

Getting Started

Prerequisites

  • Node.js (v20 or higher)
  • npm (v9 or higher)
  • Git
  • An Inworld AI account and API key

Development Setup

  1. Fork the repository on GitHub

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/language-learning-node.git
cd language-learning-node

  3. Install dependencies:

    npm install

  4. Set up environment variables: Create a backend/.env file:

    INWORLD_API_KEY=your_api_key_here
ASSEMBLY_AI_API_KEY=your_api_key_here

  5. Verify the setup:

    npm run build
npm run lint --prefix backend
npm run lint --prefix frontend

Development Workflow

Making Changes

  1. Create a feature branch:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  2. Make your changes and test them locally

  3. Run code quality checks before committing:

    # Backend
npm run lint --prefix backend           # Check for linting errors
npm run lint:fix --prefix backend       # Auto-fix linting issues
npm run format:check --prefix backend   # Verify formatting
npm run type-check --prefix backend     # Check TypeScript types

# Frontend
npm run lint --prefix frontend
npm run format:check --prefix frontend

# Build both
npm run build

  4. Commit your changes:

    git add .
git commit -m "Your descriptive commit message"

    Write clear, descriptive commit messages that explain what and why you changed something.

Code Style

TypeScript

  • Use TypeScript strict mode
  • Provide explicit types for function parameters and return values
  • Avoid any types - use unknown or proper types instead
  • Follow the existing code style and patterns
  • This project uses ESM modules (type: "module")

Formatting

  • Code is automatically formatted with Prettier
  • Run npm run format --prefix backend and npm run format --prefix frontend before committing
  • Maximum line length: 80 characters
  • Use single quotes for strings
  • Use semicolons

Linting

  • ESLint is configured with TypeScript support
  • All linting errors must be resolved before submitting a PR
  • Run npm run lint:fix --prefix backend or npm run lint:fix --prefix frontend to auto-fix issues

File Structure

language-learning-node/
├── backend/              # Backend TypeScript code
│   ├── src/
│   │   ├── __tests__/    # Backend unit tests
│   │   ├── config/       # Language & server configuration
│   │   ├── graphs/       # Inworld Runtime conversation graphs
│   │   ├── helpers/      # Audio utils, connection management
│   │   ├── prompts/      # Nunjucks prompt templates
│   │   ├── services/     # Server components
│   │   ├── utils/        # Logger
│   │   └── server.ts     # Entry point
│   └── vitest.config.ts  # Backend test config
├── frontend/             # Frontend React application
│   ├── src/
│   │   ├── __tests__/    # Frontend unit tests
│   │   ├── components/   # React components
│   │   ├── context/      # App state & auth
│   │   ├── hooks/        # Custom React hooks
│   │   ├── services/     # WebSocket client, audio, storage
│   │   ├── styles/       # CSS
│   │   └── types/        # TypeScript types
│   └── vitest.config.ts  # Frontend test config
├── supabase/
│   └── migrations/       # Database schema
└── render.yaml           # Render deployment config

Pull Request Process

  1. Update your fork:

    git checkout main
git pull upstream main
git push origin main

  2. Create your PR:

    • Push your branch to your fork
    • Open a Pull Request on GitHub
    • Fill out the PR template (if available)
    • Link any related issues

  3. PR Requirements:

    • All tests pass (if applicable)
    • Code follows style guidelines
    • Linting passes (npm run lint --prefix backend && npm run lint --prefix frontend)
    • Type checking passes (npm run type-check --prefix backend)
    • Build succeeds (npm run build)
    • Documentation is updated if needed

  4. Code Review:

    • Address any feedback from reviewers
    • Keep your PR focused on a single change
    • Keep commits clean and logical

Reporting Issues

Bug Reports

When reporting bugs, please include:

  • A clear, descriptive title
  • Steps to reproduce the issue
  • Expected behavior
  • Actual behavior
  • Environment details (Node.js version, OS, etc.)
  • Relevant code snippets or error messages

Feature Requests

For feature requests, please include:

  • A clear description of the feature
  • Use case and motivation
  • Proposed implementation approach (if you have one)

Questions?

License

By contributing, you agree that your contributions will be licensed under the MIT License.