Skip to content

Contribute.md

Latest commit

 

History

History
205 lines (155 loc) · 6.83 KB

Contribute.md

File metadata and controls

205 lines (155 loc) · 6.83 KB
Raw

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 reading our Architecture guide to understand how Lychee is structured internally. 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.3 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
  • make

Installation

  1. Clone the repository:

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

  2. Install PHP dependencies:

    composer install

  3. Install JavaScript dependencies:

    npm install

  4. Set up your environment configuration:

    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:
    php artisan migrate

  6. Start the front-end development server with hot reloading:

    npm run 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: 
    php artisan typescript:transform
npm run format

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: Our Vue3 Guide

Testing and Quality Assurance

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

PHP Quality Checks

Run PHPStan for static analysis:

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):

make test_v2
make test_unit

Apply code formatting:

make formatting

Frontend Quality Checks

Run TypeScript type checking:

npm run check

Run linting:

npm run lint

Submitting Changes

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

  1. Make your changes following the coding standards above

  2. Test your changes using the quality assurance commands

  3. Commit your changes with a clear and descriptive commit message:

git commit -m "Add feature: description of your changes"
  1. Push your branch to your fork:
git push origin feature/your-feature-name
  1. 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)

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, and npm run check)
  • 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:

Thank you for contributing to Lychee! 🌸

Last updated: August 14, 2025