Docs /contributing

Contributing to Izri

Guidelines for contributors to the Izri monorepo

📋 Overview

We welcome contributions to Izri! This guide will help you understand our development process, coding standards, and how to submit contributions effectively.

🎯 Ways to Contribute

  • 🐛 Bug Reports: Report issues you encounter
  • ✨ Feature Requests: Suggest new features
  • 📝 Documentation: Improve or add documentation
  • 💻 Code: Fix bugs or implement features
  • 🧪 Tests: Add or improve test coverage
  • 🎨 Design: Improve UI/UX

📚 Documentation Pages

Code Style

Coding standards and conventions

  • TypeScript style guide
  • React patterns
  • CSS conventions
  • File naming
  • Code organization
  • Linting and formatting with Biome
  • Best practices

Commit Conventions

Commit message conventions

  • Commit message format
  • Conventional commits
  • Breaking changes
  • Scope and description
  • Examples
  • Tools and automation

Pull Request Process

Creating and reviewing PRs

  • PR template
  • Review process
  • Testing requirements
  • Documentation updates
  • Merge criteria
  • Reviewer guidelines

Testing Guidelines

Testing strategies and best practices

  • Unit testing
  • Integration testing
  • Component testing
  • API testing
  • Test coverage requirements

🚀 Quick Start for Contributors

1. Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR-USERNAME/izri.git
cd izri

# Add upstream remote
git remote add upstream https://github.com/original-org/izri.git

2. Set Up Development Environment

# Install dependencies (we use pnpm, not npm)
pnpm install

# Set up environment
cp .env.shared.example .env.shared
# Edit .env.shared with your values
pnpm env:generate  # Generate project-specific .env files

# Start infrastructure
pnpm dev:docker

# Set up database
pnpm db:generate
pnpm db:migrate
pnpm db:seed

# Start development servers
pnpm dev

3. Create a Branch

# Update main
git checkout main
git pull upstream main

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

# Or for bug fix
git checkout -b fix/bug-description

4. Make Changes

  • Write code following our style guide
  • Add tests for new features
  • Update documentation
  • Ensure all tests pass

5. Commit Changes

# Stage changes
git add .

# Commit with conventional commit message
git commit -m "feat: add new feature"

# Or fix
git commit -m "fix: resolve bug in component"

6. Push and Create PR

# Push to your fork
git push origin feature/your-feature-name

# Create pull request on GitHub
# Fill in the PR template

📝 Commit Message Format

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks
  • perf: Performance improvements

Examples

# Feature
feat(projects): add project filtering

# Bug fix
fix(auth): resolve session expiration issue

# Documentation
docs(readme): update installation instructions

# Refactor
refactor(api): simplify project query logic

# With breaking change
feat(database)!: change project schema

BREAKING CHANGE: projects table now requires userId field

🎨 Code Style Guidelines

TypeScript

// Use explicit types
function getProject(id: string): Promise<Project> {
  // Implementation
}

// Use const for immutable values
const API_URL = 'http://localhost:4000'

// Use descriptive names
const userProjects = await fetchProjects(userId)

// Prefer arrow functions for callbacks
projects.map(project => project.name)

// Use async/await over promises
const result = await api.getProject(id)

React Components

// Use functional components
interface ProjectCardProps {
  project: Project
  onDelete: (id: string) => void
}

export function ProjectCard({ project, onDelete }: ProjectCardProps) {
  const handleDelete = () => {
    onDelete(project.id)
  }

  return (
    <div className="card">
      <h3>{project.name}</h3>
      <button onClick={handleDelete}>Delete</button>
    </div>
  )
}

// Use proper prop types
// Use descriptive variable names
// Keep components focused and small

CSS / Tailwind

// Prefer Tailwind classes
<div className="flex items-center gap-4 p-4 bg-white rounded-lg shadow">
  <span className="text-lg font-semibold">Content</span>
</div>

// Use semantic class names for custom CSS
<div className="project-card">
  ...
</div>

// Keep styles consistent
// Use responsive modifiers
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  ...
</div>

✅ Before Submitting

Checklist

  • Code follows style guidelines
  • All tests pass (pnpm test)
  • Types are correct (pnpm type:check)
  • Linting passes (pnpm lint) - we use Biome, not ESLint
  • Formatting passes (pnpm format:all) - we use Biome
  • New features have tests
  • Documentation is updated
  • Commit messages follow conventions
  • Branch is up to date with main

Run Checks

# Type check
pnpm type:check

# Lint and format (Biome)
pnpm lint
pnpm format:all

# Test
pnpm test

# Build
pnpm build

🔍 Code Review Process

For Contributors

  1. Create PR with clear description
  2. Link related issues
  3. Respond to review comments
  4. Update PR based on feedback
  5. Resolve conflicts if needed

For Reviewers

  1. Review code for quality and style
  2. Test changes locally
  3. Provide constructive feedback
  4. Approve when ready
  5. Merge or request changes

🐛 Reporting Bugs

Bug Report Template

**Description**
Clear description of the bug

**Steps to Reproduce**
1. Go to...
2. Click on...
3. See error

**Expected Behavior**
What should happen

**Actual Behavior**
What actually happens

**Environment**
- OS: macOS 13
- Node: 18.17.0
- Browser: Chrome 120

**Additional Context**
Screenshots, logs, etc.

✨ Feature Requests

Feature Request Template

**Feature Description**
Clear description of the feature

**Use Case**
Why is this feature needed?

**Proposed Solution**
How should it work?

**Alternatives Considered**
Other approaches you've considered

**Additional Context**
Mockups, examples, etc.

📖 Documentation Contributions

Guidelines

  • Clear and concise
  • Include code examples
  • Use proper formatting
  • Update TOC if needed
  • Test code examples
  • Check spelling and grammar

Documentation Structure

  • Follow existing organization
  • Use consistent formatting
  • Include relevant links
  • Add images if helpful
  • Keep it up to date

🙏 Recognition

All contributors will be recognized in:

  • GitHub contributors list
  • Release notes
  • Project README

🔗 Related Documentation

🤝 Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Help others learn and grow
  • Focus on what's best for the project
  • Assume good intentions

📞 Getting Help

  • Documentation: Start here!
  • Discussions: Ask questions
  • Issues: Report bugs
  • Discord: Real-time chat (if available)

Ready to contribute? Start with Code Style Guide →

Reading this with an agent? /docs/contributing.md serves the raw markdown.

All docs