Edit

Contribution Guidelines

This page outlines the workflow and standards for contributing to LearnHouse.

Workflow

1. Fork and Clone

Fork the LearnHouse repository on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/learnhouse.git
cd learnhouse

2. Create a Feature Branch

Always create a new branch for your changes. Use a descriptive branch name:

git checkout -b feature/your-feature-name

Branch naming conventions:

  • feature/: New features or enhancements
  • fix/: Bug fixes
  • docs/: Documentation changes
  • refactor/: Code refactoring without behavior changes

3. Make Your Changes

Develop your changes locally using the development environment. Keep commits focused and atomic.

When adding or updating dependencies:

  • Frontend: Use bun to manage JavaScript/TypeScript dependencies (e.g., bun add <package>).
  • Backend: Use uv to manage Python dependencies (e.g., uv add <package>).
  • Lockfiles: CI installs with frozen lockfiles, so commit the updated lockfiles. Run scripts/lockfiles.sh to regenerate them all.

4. Submit a Pull Request

Push your branch to your fork and open a pull request against the dev branch (the repository's default branch):

git push origin feature/your-feature-name

In your pull request description:

  • Explain what your change does and why it is needed.
  • Reference any related GitHub issues.
  • Include screenshots or recordings for UI changes.

Code Style

Frontend (TypeScript / React)

  • Use TypeScript for all new code.
  • Follow existing patterns in the codebase for component structure and naming.
  • Use functional components with hooks.
  • Format code consistently. The project includes configuration for code formatters.

Backend (Python)

  • Follow PEP 8 conventions.
  • Use type hints for function parameters and return values.
  • Write clear docstrings for public functions and classes.
  • Keep functions focused and concise.

Testing

  • Test your changes locally before submitting a pull request.
  • Verify that existing functionality is not broken by your changes.
  • For new features, include tests where applicable.

CI runs these checks on pull requests that touch each app. You can run the same commands locally:

AppDirectoryCommands
APIapps/apiuv run pytest src/tests/ -n auto and uvx ruff check .
Webapps/webbun run test, bunx tsc --noEmit (after bunx next typegen), and bun run lint:strict <changed files>
CLIapps/clibun run typecheck, bun run test, and bun run test:integration (needs Docker)

The API test suite enforces 100% coverage (set in apps/api/pyproject.toml), so add tests for every line you change. Files you change in the web app must pass the strict lint. Playwright end-to-end tests in apps/e2e run nightly.

Review Process

After submitting a pull request:

  1. A maintainer will review your code and may request changes.
  2. Address any feedback by pushing additional commits to your branch.
  3. Once approved, a maintainer will merge your pull request.

Reporting Issues

If you find a bug, please open an issue on GitHub. Include as much detail as possible: steps to reproduce, expected behavior, actual behavior, and any relevant logs or screenshots.

For a feature idea, start a Discussion in the Ideas category first. Once the team gives the go-ahead, open an issue linked to the discussion.