# 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](./code-style.md)

**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-conventions.md)

**Commit message conventions**

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

### [Pull Request Process](./pull-requests.md)

**Creating and reviewing PRs**

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

### [Testing Guidelines](./testing-guidelines.md)

**Testing strategies and best practices**

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

## 🚀 Quick Start for Contributors

### 1. Fork and Clone

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://www.conventionalcommits.org/):

```
<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

```bash
# 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

```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

```tsx
// 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

```tsx
// 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

```bash
# 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

```markdown
**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

```markdown
**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

- **Getting Started**: [Installation Guide](../getting-started/installation.md)
- **Development**: [Development Guide](../development/README.md)
- **Architecture**: [Design Decisions](../architecture/design-decisions.md)

## 🤝 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](./code-style.md) →*