# Contributing to Lychee

Thank you for your interest in contributing to Lychee! This guide will help you get started with contributing to the project.

## Getting Started

Before you start contributing, we recommend reviewing our documentation structure:
- [Overview](specs/0-overview/README.md) - High-level introduction to Lychee
- [Core Concepts](specs/1-concepts/README.md) - Domain model and fundamental concepts
- [Reference Documentation](specs/3-reference/) - Coding conventions, frontend architecture
- [Architecture Documentation](specs/4-architecture/) - Knowledge map and feature specs

This will help you navigate the codebase more effectively.

1. Fork the repository on GitHub
2. Clone your fork locally
3. Set up your development environment
4. Create a new branch for your feature or bug fix
5. Make your changes
6. Test your changes
7. Submit a pull request

## Development Environment Setup

### Prerequisites

- PHP 8.4 or higher
- php extensions:
  - `php-curl`
  - `php-mbstring`
  - `php-xml`
  - `php-mysql` (usually used for your local database)
  - `php-gd`
  - `php-zip`
  - `php-bcmath`
  - `php-imagick`
  - `php-exif`
  - `php-openssl`
  - `php-redis`
  - `php-intl`
  - `php-sqlite3` (recommended for running the tests)
- Composer
- Node.js and npm, plus the Vite+ CLI (`vp`, https://viteplus.dev/guide/; after `npm install` the project-local binary also runs as `npx vp …`)
- make

### Installation

1. Clone the repository:
    ```bash
    git clone https://github.com/YOUR_USERNAME/Lychee.git
    cd Lychee
    ```

2. Install PHP dependencies:
    ```bash
    composer install
    ```

3. Install JavaScript dependencies:
    ```bash
    npm install
    ```

4. Set up your environment configuration:
    ```bash
    cp .env.example .env
    php artisan key:generate
    ```

5. Set up the database:
    - Create a new database (e.g., `lychee`)
    - Update the `.env` file with your database credentials
    - Run the migrations:
    ```bash
    php artisan migrate
    ```

5. Start the front-end development server with hot reloading:
  	```bash
  	vp dev
  	```

## Code Standards and Quality

### PHP Standards

We follow strict coding standards for PHP development:

- **PSR-4 coding standard** is applied throughout the codebase (in practice, this means that the filename should match the class name and be in the correct directory structure)
- **Variable names** should be in `snake_case` (rector is used to enforce this)
- Use **strict comparison** `===` instead of loose comparison `==` (phpstan will validate this)
- Only **booleans** should be used in if statements, not integers or strings (phpstan will validate this)
- Use `in_array()` with `true` as the third parameter for strict comparison (phpstan will validate this)
- **Avoid code duplication** in both if and else statements
- **Do not use `empty()`** - use explicit checks instead (phpstan will validate this)
- All new files must contain the **license header** with a single blank line after the opening PHP tag (just take example on an existing file)

### Application-Specific Conventions

- In Request classes, `$this->user` is reserved for the user making the request
- In Request classes, if a user is provided by the query, it should be placed in `$this->user2`
- Resource classes used for the serialization of the response should extend from **Spatie Data** instead of JsonResource. In the case of Collections, in order to get proper typing, use `#[LiteralTypeScriptType('...')]` This will ensure that the types responses types are properly generated.
- We use **Vue3** instead of Blade views
- If you modify or add a Resource class, ensure that the TypeScript types are properly generated by running:
  ```bash
  php artisan typescript:transform
  vp check --fix
  ```

### Vue3/TypeScript Standards

- Use **TypeScript** in composition API for Vue3
- Use **PrimeVue** for UI components
- **Do not use `await` async calls** in Vue3, use `.then()` instead
- **Do not use arrow functions** for function declarations: use `function functionName() {}` instead of `const function = () => {}`

Read more here: [Frontend Architecture](specs/3-reference/frontend-architecture.md)

## Testing and Quality Assurance

Before submitting your pull request, ensure all quality checks pass:

### PHP Quality Checks

Run PHPStan for static analysis:
```bash
make phpstan
```

Run the test suite (note that this will use sqlite3 as a database, so that you can have test data on your mysql database and run the tests in parallel):
```bash
make test_v2
make test_unit
```

Apply code formatting:
```bash
make formatting
```

### Frontend Quality Checks

Run TypeScript type checking:
```bash
vp run typecheck
```

Run formatting and linting:
```bash
vp check --fix
```

## Submitting Changes

1. **Create a new branch** for your feature or bug fix:
```bash
git checkout -b feature/your-feature-name
```

2. **Make your changes** following the coding standards above

3. **Test your changes** using the quality assurance commands

4. **Commit your changes** with a clear and descriptive commit message:
```bash
git commit -m "Add feature: description of your changes"
```

5. **Push your branch** to your fork:
```bash
git push origin feature/your-feature-name
```

6. **Create a pull request** on GitHub with:
   - A clear title describing the change
   - A detailed description of what was changed and why
   - References to any related issues
   - Screenshots (if applicable for UI changes)

## Using AI/Claude for Contributions

AI-assisted development is permitted and welcomed. However, contributions using AI tools must follow our **Specification-Driven Development (SDD)** workflow:

### Guidelines

1. **Read [AGENTS.md](../AGENTS.md) first** — This file contains the instructions that guide AI agents working on this codebase. It defines the workflow, guardrails, and expectations for AI-assisted development.

2. **Follow Spec-Driven Development** — AI-generated code must be anchored in explicit specifications:
   - Start by creating or updating the feature specification at `docs/specs/4-architecture/features/<NNN>-<feature-name>/spec.md`
   - Generate a feature plan (`plan.md`) and tasks checklist (`tasks.md`)
   - Write tests before implementation (test-first cadence)
   - Use the templates in `docs/specs/templates/` for consistency

3. **Understand before generating** — AI tools should explore and understand the existing codebase before proposing changes. Use the documentation structure in `docs/specs/` to build context.

4. **Quality gates still apply** — All AI-generated code must pass the same quality checks as human-written code:
   - PHPStan static analysis
   - Full test suite
   - Code formatting (php-cs-fixer, Oxfmt)
   - TypeScript type checking

5. **Review and understand all output** — Contributors are responsible for understanding and validating any AI-generated code before submitting. Do not submit code you don't understand.

6. **Document open questions** — When AI encounters ambiguity, log questions in the feature's `docs/specs/4-architecture/features/<NNN>-<feature-name>/open-questions.md` and wait for clarification before proceeding.

### Recommended AI Models

We recommend using **Claude Sonnet or Claude Opus** for AI-assisted contributions. Avoid free-tier models from GitHub Copilot as they tend to hallucinate heavily and struggle to follow structured task files.

When using **Claude Code**, reference `@AGENTS.md` as the first step in your conversation to guide the agent through the SDD workflow.

### Two-PR Workflow (Recommended)

For SDD contributions, we recommend splitting your work into **two pull requests**:

1. **Specification PR** — Submit the spec, plan, and tasks files first. This allows maintainers to review the proposed approach before implementation begins.
2. **Implementation PR** — Once the specification is approved, submit the implementation that builds from the approved spec.

This workflow ensures that:
- The specification can be reviewed and refined before any code is written
- Time and resources are not wasted on implementations that don't align with project goals
- The spec serves as a clear contract for what the implementation should deliver

### Small Fixes Exception

The full SDD workflow is not required for trivial changes such as:
- Typo fixes
- Single-line bug fixes with obvious solutions
- Minor documentation corrections
- Simple configuration changes

For these cases, a direct PR without specifications is acceptable. Use your judgment — if the change requires design decisions or affects multiple files, use SDD.

### Why SDD with AI?

Specification-Driven Development ensures that AI-assisted contributions:
- Are traceable back to explicit requirements
- Follow established architectural patterns
- Maintain test coverage organically
- Don't introduce undocumented behavior or "magic" code

## Pull Request Guidelines

- Keep your changes focused and atomic
- ~~Write clear, descriptive commit messages~~ We don't care about the commit messages, as our commit history is squashed when merging pull requests. Just make sure that the final diff is clean.
- Include tests for new functionality
- Update documentation if necessary
- Ensure all quality checks pass (i.e., run `make phpstan`, `make test_v2`, `vp check` and `vp run typecheck`)
- Be responsive to feedback during code review (if you are not responsive, we will close the pull request after 2 weeks of inactivity).

## Reporting Issues

We welcome bug reports and feature requests, however we no longer allow the creation of github issues. This is to ensure that we can focus on the most important issues and features without being overwhelmed by noise.

When creating an issue, you will be proposed to create a discussion instead.
We will do our best to reply to those and transform them into issues when necessary. Please make sure to follow the template provided in the discussion.
If you are asked with further question to clarify, please make sure to reply within 2 weeks, otherwise we will reserve the right to close the discussion.

## Getting Help

If you need help or have questions:

- Check the [existing documentation](https://lycheeorg.dev/docs/)
- Review the [documentation structure](specs/) to understand how Lychee is organized
- Check the already existing [discussions](https://github.com/LycheeOrg/Lychee/discussions) (closed and open).
- Check the already existing [issues](https://github.com/LycheeOrg/Lychee/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen) and [pull requests](https://github.com/LycheeOrg/Lychee/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen).
- Create a new discussion if necessary or join our [discord](https://discord.gg/JMPvuRQcTf) and post into the #help channel.

Thank you for contributing to Lychee! 🌸

---

*Last updated: January 21, 2026*