Contributing

Welcome to the Pelican project! We are excited to have you contribute to our open-source project. This guide will help you get started with setting up your development environment, understanding our coding standards, and making your first or next contribution.

Getting started

To start contributing to Pelican Panel, you need to have a basic understanding of the following:

Dev Environment Setup

Fork the Repository
Clone your Fork
Install Dependencies (PHP modules & composer, and run composer install)
Configure your Environment (via php artisan p:environment:setup)
Set up your Database (via php artisan p:environment:database) and run Migrations (via php artisan migrate --seed --force)
Create your first Admin User (via php artisan p:user:make)
Start your Webserver (e.g. Nginx or Apache)

As IDE we recommend Visual Studio/ Visual Studio Code (free) or PhpStorm (paid).

To easily install PHP and the Webserver we recommend Laravel Herd. (Windows & macOS)
The (paid) Pro version of Laravel Herd also offers easy MySQL and Redis hosting, but the free version is fine for most cases.

Coding Standards

We use PHPStan/ Larastan and PHP-CS-Fixer/ Pint to enforce certain code styles and standards. You can run PHPStan via \vendor\bin\phpstan analyse and Pint via \vendor\bin\pint.

Testing

Running Tests

By default, tests run in parallel to speed up the test suite execution:

# Run all tests in parallel (default behavior)
php artisan test

# Run with explicit process count
php artisan test --processes=4

# Run tests sequentially (disable parallel execution)
php artisan test --processes=1

Writing Parallel-Safe Tests

When writing tests, follow these guidelines to ensure they run correctly in parallel:

Avoid shared state: Each test should be independent and not rely on data created by other tests
Use unique identifiers: Generate unique names, emails, or other identifiers to avoid conflicts between parallel processes
Clean up after yourself: Use database transactions or ensure proper cleanup in tearDown methods
Avoid race conditions: Be careful with file system operations, external services, or global state

Debugging Test Isolation Issues

If you encounter flaky tests or failures that only occur in parallel execution:

Run tests sequentially to confirm the issue is parallel-related:
```
php artisan test --processes=1
```
Run a specific test in isolation:
```
php artisan test --filter=YourTestName
```
Check for shared resources: Look for database records, files, or cache entries that might be shared between tests
Add database transactions: Ensure your tests use database transactions to isolate database changes

Making Contributions

From your forked repository, make your own changes on your own branch. (do not make changes directly to main!)
When you are ready, you can submit a pull request to the Pelican repository. If you still work on your pull request or need help with something make sure to mark it as Draft.

Also, please make sure that your pull requests are as targeted and simple as possible and don't do a hundred things at a time. If you want to add/ change/ fix 5 different things you should make 5 different pull requests.

Translations

If you add any new translation strings make sure to only add them to english.
Other languages are translated via Crowdin.

Code Review Process

Your pull request will then be reviewed by the maintainers.
Once you have an approval from a maintainer, another will merge it once it’s confirmed.

Depending on the pull request size this process can take multiple days.

Community and Support

Help: Discord
Bugs: GitHub Issues
Features: GitHub Discussions
Security vulnerabilities: See our security policy.

4.4 KiB Raw Permalink Blame History Unescape Escape