Руководство по внесению вкладов

• Сообщения об ошибках
• Вопросы поддержки
• Обсуждение основного развития
• Какую ветку использовать?
• Скомпилированные ассеты
• Уязвимости безопасности
• Стиль кодирования
  • PHPDoc
  • StyleCI
• Кодекс поведения

#Сообщения об ошибках

Для активного сотрудничества Laravel настоятельно рекомендует создавать pull requests, а не просто сообщения об ошибках. Pull requests будут рассматриваться только если они помечены как «готовы к проверке» (не в состоянии «draft») и все тесты для новых функций проходят успешно. Затянувшиеся, неактивные pull requests в состоянии «draft» будут закрыты через несколько дней.

Если вы создаёте сообщение об ошибке, оно должно содержать заголовок и чёткое описание проблемы. Также следует включить как можно больше релевантной информации и пример кода, демонстрирующий ошибку. Цель сообщения об ошибке — упростить для вас и других воспроизведение бага и разработку исправления.

Помните, что сообщения об ошибках создаются в надежде, что другие с такой же проблемой смогут вместе с вами её решить. Не стоит ожидать, что сообщение автоматически вызовет активность или что кто-то сразу возьмётся за исправление. Создание сообщения об ошибке помогает вам и другим начать путь к решению проблемы. Если хотите помочь, вы можете исправить любые ошибки, указанные в наших трекерах. Для просмотра всех issues Laravel необходимо быть аутентифицированным на GitHub.

Если вы заметили некорректные DocBlock, предупреждения PHPStan или IDE при работе с Laravel, не создавайте issue на GitHub. Вместо этого отправьте pull request с исправлением.

Исходный код Laravel управляется на GitHub, и для каждого проекта Laravel есть отдельные репозитории:

#Вопросы поддержки

Трекеры issues Laravel на GitHub не предназначены для оказания помощи или поддержки. Вместо этого используйте один из следующих каналов:

#Обсуждение основного развития

Вы можете предложить новые функции или улучшения существующего поведения Laravel в репозитории Laravel framework на GitHub discussion board. Если вы предлагаете новую функцию, будьте готовы реализовать хотя бы часть кода, необходимого для её завершения.

Неформальное обсуждение багов, новых функций и реализации существующих функций происходит в канале #internals на Laravel Discord сервере. Тейлор Отвелл, поддерживающий Laravel, обычно присутствует в канале по будням с 8:00 до 17:00 (UTC-06:00 или America/Chicago) и время от времени в другое время.

#Какую ветку использовать?

Все исправления ошибок должны отправляться в последнюю версию, поддерживающую исправления (в настоящее время 10.x). Исправления ошибок никогда не должны отправляться в ветку master, если они не исправляют функции, существующие только в предстоящем релизе.

Незначительные функции, которые полностью обратно совместимы с текущим релизом, могут отправляться в последнюю стабильную ветку (в настоящее время 10.x).

Крупные новые функции или функции с несовместимыми изменениями всегда должны отправляться в ветку master, которая содержит предстоящий релиз.

#Скомпилированные ассеты

Если вы отправляете изменение, которое повлияет на скомпилированный файл, например большинство файлов в resources/css или resources/js репозитория laravel/laravel, не коммитьте скомпилированные файлы. Из-за их большого размера их невозможно эффективно проверить мейнтейнером. Это может быть использовано для внедрения вредоносного кода в Laravel. Чтобы предотвратить это, все скомпилированные файлы будут генерироваться и коммититься мейнтейнерами Laravel.

#Уязвимости безопасности

Если вы обнаружили уязвимость безопасности в Laravel, пожалуйста, отправьте письмо Тейлору Отвеллу на taylor@laravel.com. Все уязвимости безопасности будут оперативно устранены.

#Стиль кодирования

Laravel следует стандарту кодирования PSR-2 и стандарту автозагрузки PSR-4.

#PHPDoc

Ниже приведён пример корректного блока документации Laravel. Обратите внимание, что атрибут @param сопровождается двумя пробелами, затем типом аргумента, ещё двумя пробелами и, наконец, именем переменной:

/**
 * Register a binding with the container.
 *
 * @param  string|array  $abstract
 * @param  \Closure|string|null  $concrete
 * @param  bool  $shared
 * @return void
 *
 * @throws \Exception
 */
public function bind($abstract, $concrete = null, $shared = false)
{
    // ...
}

Когда атрибуты @param или @return избыточны из-за использования нативных типов, их можно опустить:

/**
 * Execute the job.
 */
public function handle(AudioProcessor $processor): void
{
    //
}

Однако, если нативный тип является обобщённым, указывайте обобщённый тип с помощью атрибутов @param или @return:

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

#StyleCI

Не беспокойтесь, если стиль вашего кода не идеален! StyleCI автоматически объединит любые исправления стиля в репозиторий Laravel после слияния pull requests. Это позволяет сосредоточиться на содержании вклада, а не на стиле кода.

#Кодекс поведения

Кодекс поведения Laravel основан на кодексе поведения Ruby. Любые нарушения кодекса поведения можно сообщить Тейлору Отвеллу (taylor@laravel.com):