Посібник з внеску

Повідомлення про помилки

Щоб заохотити активну співпрацю, Laravel наполегливо радить надсилати pull request'и, а не просто повідомлення про помилки. Pull request'и розглядатимуться лише тоді, коли їх позначено як «ready for review» (тобто не в стані «draft») і всі тести для нових можливостей проходять. Застарілі неактивні pull request'и, залишені у стані «draft», будуть закриті за кілька днів.

Утім, якщо ви створюєте повідомлення про помилку, воно має містити заголовок і чіткий опис проблеми. Також варто додати якомога більше доречної інформації та приклад коду, що демонструє проблему. Мета повідомлення про помилку - полегшити вам і іншим відтворення помилки та розробку виправлення.

Пам'ятайте: повідомлення про помилки створюються з надією, що інші з такою самою проблемою зможуть співпрацювати з вами над її розв'язанням. Не очікуйте, що повідомлення автоматично привабить увагу або що хтось кинеться його виправляти. Створення повідомлення допомагає вам та іншим стати на шлях вирішення проблеми. Якщо хочете долучитися, можете допомогти, виправивши будь-яку з помилок у наших трекерах. Щоб побачити всі issue Laravel, потрібно бути автентифікованим на GitHub.

Якщо під час роботи з Laravel ви помітили некоректний DocBlock або попередження PHPStan чи IDE, не створюйте issue на GitHub. Натомість надішліть pull request із виправленням.

Вихідний код Laravel розміщено на GitHub, і для кожного з проєктів Laravel є свій репозиторій:

Питання щодо підтримки

Трекери issue на GitHub не призначені для надання допомоги чи підтримки щодо Laravel. Натомість скористайтеся одним із таких каналів:

Обговорення розробки ядра

Ви можете пропонувати нові можливості або покращення наявної поведінки Laravel на дошці обговорень GitHub у репозиторії фреймворку. Якщо ви пропонуєте нову можливість, будьте готові реалізувати хоча б частину коду, потрібного для її втілення.

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

Яку гілку обрати?

Усі виправлення помилок слід надсилати до найновішої версії, яка підтримує виправлення помилок (наразі 13.x). Виправлення помилок ніколи не слід надсилати до гілки master, окрім випадків, коли вони виправляють можливості, що існують лише в майбутньому релізі.

Незначні можливості, повністю зворотно сумісні з поточним релізом, можна надсилати до останньої стабільної гілки (наразі 13.x).

Великі нові можливості або можливості зі змінами, що порушують сумісність, завжди слід надсилати до гілки master, яка містить майбутній реліз.

Скомпільовані ресурси

Якщо ви надсилаєте зміну, яка вплине на скомпільований файл - як-от більшість файлів у resources/css чи resources/js репозиторію laravel/laravel, - не комітьте скомпільовані файли. Через їхній великий розмір супровідник не зможе реально їх перевірити. Цим можна скористатися, щоб впровадити зловмисний код у Laravel. Щоб запобігти цьому, усі скомпільовані файли генеруються й комітяться супровідниками Laravel.

Внески, згенеровані AI

Ми цінуємо кожен pull request, надісланий до Laravel. Однак внески, здебільшого згенеровані AI без вдумливого перегляду й осмислення людиною, неприйнятні.

Якщо ви вирішили скористатися AI-інструментами для підготовки свого внеску, отриманий код обов'язково має бути ретельно переглянутий, протестований і зрозумілий вам перед надсиланням.

Масове створення issue чи pull request'ів, повністю згенерованих AI, не буде терпітися. Такі pull request'и закриватимуться без розгляду, а користувача, який їх надіслав, може бути заблоковано в репозиторії.

Ми заохочуємо контриб'юторів ознайомлюватися з наявною кодовою базою, взаємодіяти зі спільнотою та надсилати pull request'и, які відображають їхнє власне розуміння й уважне осмислення проблеми, яку вони розв'язують.

Вразливості безпеки

Якщо ви виявили вразливість безпеки в Laravel, надішліть листа нашій команді безпеки на security@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.
 * [tl! remove]
 * @return void [tl! remove]
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

Однак якщо нативний тип є узагальненим (generic), вкажіть узагальнений тип за допомогою атрибутів @param чи @return:

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

StyleCI

Не хвилюйтеся, якщо стиль вашого коду не бездоганний! StyleCI автоматично зіллє всі виправлення стилю до репозиторію Laravel після злиття pull request'ів. Це дозволяє нам зосередитися на змісті внеску, а не на стилі коду.

Кодекс поведінки

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