Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
360 lines (259 loc) · 8.08 KB

CONTRIBUTING.md

File metadata and controls

360 lines (259 loc) · 8.08 KB

Contributing to laroux

Thank you for your interest in contributing to laroux! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

Be respectful, inclusive, and collaborative. We're all here to build something great together.

Getting Started

Prerequisites

  • Deno v2.6 or later
  • Git
  • Basic understanding of React Server Components
  • Familiarity with TypeScript

Setting Up Development Environment

  1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/laroux.git
cd laroux
  1. Explore the codebase
# View the project structure
ls -R packages/

# Read the implementation plan
cat docs/implementation.md

# Check out the user guide
cat docs/user-guide.md
  1. Run the tests
# Run all tests
deno test --unstable-bundle --allow-all

# Run specific test file
deno test packages/laroux-bundler/chunk-manifest.test.ts
  1. Try the CLI locally
# Create a test project
deno run --unstable-bundle --allow-all packages/laroux/cli.ts init test-app

# Start dev server
cd test-app
deno run --unstable-bundle --allow-all ../packages/laroux/cli.ts dev

Project Structure

laroux/
├── packages/
│   ├── laroux/              # CLI package
│   │   ├── cli.ts           # Main entry point
│   │   ├── commands/        # CLI commands
│   │   └── templates/       # Project templates
│   ├── laroux-core/         # Core runtime
│   │   ├── runtime/         # Server, RSC handler, actions
│   │   ├── config/          # Configuration system
│   │   ├── cli-formatting.ts
│   │   └── error-formatting.ts
│   ├── laroux-bundler/      # Build system
│   │   ├── runtime-bundler.ts
│   │   ├── prebuilt-bundler.ts
│   │   └── client/          # Client components
│   ├── laroux-server/       # Server orchestration
│   └── laroux-rsc/          # RSC implementation
├── docs/                    # Documentation
└── tests/                   # Integration tests

How to Contribute

Reporting Bugs

  1. Check existing issues to avoid duplicates
  2. Create a new issue with:
    • Clear, descriptive title
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (Deno version, OS)
    • Error messages and stack traces

Suggesting Features

  1. Check existing issues for similar suggestions
  2. Create a feature request with:
    • Clear use case
    • Proposed API or behavior
    • Why it would benefit the project
    • Potential implementation approach (if applicable)

Code Contributions

Step 1: Pick an Issue

  • Look for issues labeled good first issue or help wanted
  • Comment on the issue to let others know you're working on it
  • Ask questions if anything is unclear

Step 2: Create a Branch

# Create a feature branch
git checkout -b feature/your-feature-name

# Or a bugfix branch
git checkout -b fix/issue-description

Step 3: Make Changes

Follow these guidelines:

Code Style

  • Use TypeScript for all code
  • Follow existing code patterns and conventions
  • Use descriptive variable and function names
  • Add JSDoc comments for public APIs

File Naming

  • Use domain-specific names (NOT "utils", "helpers", "common")
  • Examples:
    • ✅ cli-formatting.ts, error-formatting.ts, chunk-manifest.ts
    • ❌ utils.ts, helpers.ts, common.ts

Imports

  • Use explicit imports from specific modules
  • Avoid barrel exports when possible
  • Group imports: external → internal → relative

Error Handling

  • Use structured error classes from error-formatting.ts
  • Provide helpful error messages with hints
  • Include relevant context in errors

Example:

import { ConfigError, errors } from "@eser/laroux-core/error-formatting";

// Use error factories
throw errors.invalidConfig(
  "./laroux.config.ts",
  "Export must be a default export",
);

// Or create custom errors
throw new ConfigError(
  "Invalid port number",
  "Port must be between 1024 and 65535",
);

Testing

  • Add tests for new features
  • Ensure existing tests pass
  • Use descriptive test names
Deno.test("ChunkManifest - should register chunk with dependencies", () => {
  const manifest = new ChunkManifest();
  manifest.addChunk("counter", {
    path: "/chunks/counter-abc123.js",
    dependencies: ["react", "shared"],
  });

  const chunk = manifest.getChunk("counter");
  assertEquals(chunk.dependencies, ["react", "shared"]);
});

Step 4: Commit Changes

Use conventional commit messages:

# Format: type(scope): description

git commit -m "feat(bundler): add CSS processing support"
git commit -m "fix(cli): resolve template path on Windows"
git commit -m "docs(readme): update installation instructions"
git commit -m "test(config): add tests for config merging"

Commit types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • test: Adding or updating tests
  • refactor: Code refactoring
  • perf: Performance improvements
  • chore: Maintenance tasks

Step 5: Push and Create PR

# Push your branch
git push origin feature/your-feature-name

# Create a pull request on GitHub

Pull Request Guidelines

  • Reference related issues (e.g., "Fixes #123")
  • Describe what changed and why
  • Include screenshots for UI changes
  • Check that all tests pass
  • Respond to review feedback

Development Workflow

Running Tests

# Run all tests
deno test --unstable-bundle --allow-all

# Run with coverage
deno test --unstable-bundle --allow-all --coverage=coverage

# Watch mode
deno test --unstable-bundle --allow-all --watch

Testing Changes Locally

# Create a test project
deno run --unstable-bundle --allow-all packages/laroux/cli.ts init test-app

# Test dev command
cd test-app
deno run --unstable-bundle --allow-all ../packages/laroux/cli.ts dev

# Test build command
deno run --unstable-bundle --allow-all ../packages/laroux/cli.ts build

# Test serve command
deno run --unstable-bundle --allow-all ../packages/laroux/cli.ts serve

Debugging

# Enable debug logging
deno run --unstable-bundle --allow-all packages/laroux/cli.ts dev --log-level=debug

# Use Deno's debugger
deno run --inspect-brk --unstable-bundle --allow-all packages/laroux/cli.ts dev

Package-Specific Guidelines

laroux-core

  • Keep runtime code performant
  • Minimize dependencies
  • Document all exported APIs
  • Add helpful error messages

laroux-bundler

  • Optimize bundle sizes
  • Support incremental compilation
  • Test with various project structures
  • Handle edge cases gracefully

laroux (CLI)

  • Provide clear, actionable feedback
  • Use colored output for better UX
  • Include progress indicators for long operations
  • Handle errors gracefully with helpful hints

Templates

  • Keep templates minimal but functional
  • Include comments explaining key concepts
  • Use best practices
  • Test on multiple platforms

Documentation

README Files

  • Keep package READMEs up to date
  • Include usage examples
  • Document all public APIs
  • Link to related documentation

User Guide

Update docs/user-guide.md when:

  • Adding new features
  • Changing CLI commands
  • Updating configuration options
  • Adding new templates

Release Process

(For maintainers)

  1. Update version in all jsr.json files
  2. Update CHANGELOG.md with release notes
  3. Run all tests and ensure they pass
  4. Create a git tag (e.g., v3.0.0)
  5. Publish to JSR:
# Publish each package
cd packages/laroux-core
deno publish

cd ../laroux-bundler
deno publish

cd ../laroux
deno publish

Getting Help

Recognition

Contributors will be:

  • Listed in the project README
  • Credited in release notes
  • Thanked in the community

Thank you for contributing to laroux! 🦕