Руководство по участию в проекте

Статистика: Символов — 8 715/7 510 без пробелов (7 844/6 762 без кода):, слов — 1 083
Разметка: Wiki
{{TOC}}

{{DOCVER  4.2=d7b13440c003218ed79e9d508706eca01990122f 4.12.2014 5:01:15}}

== Введение ==

Laravel - проект с открытым исходным кодом, и любой может внести свой вклад в его развитие. Мы рады каждому, независимо от его уровня квалификации, пола, расы, религии и национальности. Разнообразное, яркое сообщество - одна из основных ценностей фреймворка!

Для поощрения активного сотрудничества Laravel в настоящее время принимает только pull-запросы и не принимает отчёты об ошибках. Отчёты об ошибках могут быть отправлены в форме pull-запроса, содержащего непройденный unit-тест. Кроме того, демонстрация бага в sandbox-приложении может быть отправлена как pull-запрос в ((https://github.com/laravel/laravel основной репозиторий Laravel)). Непройденные unit-тесты и sandbox-приложения дают команде разработчиков "доказательство" того, что ошибка существует, а после её исправления служат надёжным показателем того, что ошибка была исправлена.

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

  * ((https://github.com/laravel/framework Laravel Framework))
  * ((https://github.com/laravel/laravel Laravel Application))
  * ((https://github.com/laravel/docs Laravel Documentation))
  * ((https://github.com/laravel/cashier Laravel Cashier))
  * ((https://github.com/laravel/envoy Laravel Envoy))
  * ((https://github.com/laravel/homestead Laravel Homestead))
  * ((https://github.com/laravel/settler Laravel Homestead Build Scripts))
  * ((https://github.com/laravel/laravel.com Laravel Website))
  * ((https://github.com/laravel/art Laravel Art))

== Об основном ядре ==

Обсуждение ошибок, новых функций и применения существующих функций происходит на IRC-канале %%(t)#laravel-dev%% (Freenode). Тейлор Отвелл, создатель Laravel, обычно находится на канале по будням с 11 вечера до 8 утра (по Москве), а иногда и в другое время.

IRC-канал %%(t)#laravel-dev%% открыт для всех. Мы приглашаем всех зайти на канал для участия в обсуждении или просто понаблюдать!

== Новые функции ==

Перед отправкой pull-запросов по новым функциям, пожалуйста, свяжитесь с Тейлором Отвеллом через %%(t)#laravel-dev%%. Если функция окажется подходящей для фреймворка, вы можете сделать pull-запрос. Даже если функция будет отклонена, не сдавайтесь! Вы всё ещё можете превратить свою функцию в package, который может быть выпущен в свет с помощью ((https://packagist.org/ Packagist)).

При добавлении новых функций, не забудьте добавить unit-тесты! Unit-тесты помогут обеспечить стабильность и надёжность фреймворка после добавления функции.

== Отчёты об ошибках ==

=== С помощью unit-тестов ===

Pull-запросы по ошибкам могут быть отправлены без предварительного обсуждения с командой разработчиков Laravel. Когда будете отправлять отчёт об ошибке, постарайтесь включить в него unit-тест, чтобы мы могли гарантировать, что ошибка никогда не появится снова!

Если вы считаете, что нашли ошибку во фреймворке, но не знаете, как её исправить, пожалуйста, отправьте pull-запрос, содержащий непройденный unit-тест. Непройденные unit-тесты дают команде разработчиков "доказательство", что ошибка существует, а после её исправления служат надёжным показателем того, что ошибка была исправлена.

Если вы не знаете, как написать правильный unit-тест для найденной ошибки, просмотрите другие unit-тесты, включенные во фреймворк. Если это не поможет, обратитесь за помощью на канал %%(t)#laravel-dev%%.

=== С помощью Laravel Liferaft ===

Если вы не можете написать unit-тест для вашей проблемы, то используйте Laravel Liferaft. Он позволяет создать демо-приложение, которое воспроизводит эту проблему. Liferaft может даже автоматизировать процесс подключения и передачи pull-запросов в репозиторий Laravel. После того, как ваше Liferaft-приложение отправлено, разработчик Laravel сможет запустить приложение на ((/docs/v4/homestead Homestead)) и рассмотреть вашу проблему.

== Создание Liferaft-приложений ==

Laravel Liferaft предоставляет новый, инновационный способ внести свой вклад в развитие Laravel. Для начала нужно установить консольный инструмент Liferaft с помощью Composer:

=== Установка Liferaft ===
%%(sh)
  composer global require "laravel/liferaft=~1.0"
%%

Не забудьте поместить путь %%(t)~/.composer/vendor/bin%% в переменную %%(t)PATH%%, чтобы исполняемый файл %%(t)liferaft%% был найден при запуске команды %%(t)liferaft%% в терминале.

=== Аутентификация через GitHub ===

Перед началом работы с Liferaft вам необходимо зарегистрировать личный токен доступа GitHub. Вы можете сгенерировать его в ((https://github.com/settings/applications панели настроек GitHub)). По умолчанию предоставленного GitHub'ом места будет достаточно. Однако, если захотите, вы можете выбрать дисковое пространство %%(t)delete_repo%%, тогда Liferaft сможет удалять ваши старые sandbox-приложения.
%%(sh)
  liferaft auth my-github-token
%%

=== Создание нового Liferaft-приложения ===

Чтобы создать новое Liferaft-приложение, просто используйте команду %%(sh)new%%:
%%(sh)
  liferaft new my-bug-fix
%%

Эта команда будет выполнять несколько вещей. Во-первых, она подключит ((https://github.com/laravel/laravel репозиторий Laravel GitHub)) к вашей учётной записи GitHub. Затем, она клонирует подключенное хранилище на вашу машину и установит зависимости Composer. После того как хранилище будет установлено, вы сможете воспроизвести свою проблему в пределах Liferaft-приложения!

=== Воспроизведение проблемы ===

Создав Liferaft-приложение, воспроизведите вашу проблему. Вы неограничены в задании маршрутов, создании Eloquent-моделей и даже создании миграций баз данных! Единственное требование - ваше приложение должно запускаться на чистой виртуальной машине ((/docs/v4/homestead Laravel Homestead)). Это позволит специалистам Laravel легко запустить ваше приложение на своих машинах.

Как только вы воспроизвели свою проблему в Liferaft-приложении, вы можете отправить его обратно в репозиторий Laravel на рассмотрение!

=== Отправка вашего приложения на рассмотрение ===

Как только вы воспроизвели свою проблему, вы уже почти можете послать её на рассмотрение! Однако сначала вы должны заполнить файл %%(t)liferaft.md%%, который был сгенерирован в вашем Liferaft-приложении. Первая строка этого файла будет названием вашего pull-запроса. Остальные строки будут включены в тело pull-запроса. Конечно же, разметка GitHub поддерживается.

После завершения работы с файлом %%(t)liferaft.md%%, отправьте все ваши изменения в репозиторий GitHub. Далее просто запустите Liferaft-команду %%(sh)throw%% из директории вашего приложения:
%%(sh)
  liferaft throw
%%

Эта команда создаст pull-запрос в репозиторий Laravel GitHub. Разработчик Laravel сможет легко получить ваше приложение и запустить его в своей собственной Homestead-среде!

== Получение Liferaft-приложения ==

Хотите участвовать в развитии Laravel? С помощью Liferaft вы легко сможете устанавливать Liferaft-приложения и изучать их в собственной ((/docs/v4/homestead Homestead-среде)).

Для удобства сначала клонируйте ((https://github.com/laravel/laravel laravel/laravel)) в каталог %%(t)liferaft%% на вашем компьютере:
%%(sh)
  git clone https://github.com/laravel/laravel.git liferaft
%%

Затем обновите локальную ветку %%(t)develop%%, чтобы устанавливать Liferaft-приложения, ориентированные как на выпущенные, так и предстоящие релизы Laravel:
%%(sh)
  git checkout -b develop origin/develop
%%

После этого вы можете запустить Liferaft-команду %%(sh)grab%% из директории вашего репозитория. Например, если вы хотите установить Liferaft-приложение, связанное с pull-запросом #3000, вы должны выполнить следующую команду:
%%(sh)
	liferaft grab 3000
%%

Команда %%(sh)grab%% создаст новую ветку в вашей директории Liferaft, и синхронизирует изменения для указанного pull-запроса. После установки Liferaft-приложения просто откройте эту директорию через виртуальную машину ((/docs/v4/homestead Homestead))! После отладки проблемы не забудьте отправить pull-запрос в репозиторий ((https://github.com/laravel/framework laravel/framework)) с соответствующим исправлением!

У вас появился свободный часок и вы хотите решить какую-нибудь проблему? Просто запустите %%(sh)grab%% без указания ID pull-запроса:
%%(sh)
  liferaft grab
%%

== Какая ветка? ==

.(alert)
Этот раздел в основном относится к тем, кто отправляет pull-запросы в репозиторий ((https://github.com/laravel/framework laravel/framework)), а не Liferaft-приложения.

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

**Незначительные** новые функции, имеющие **полную обратную совместимость** с текущей версией Laravel могут быть отправлены в последнюю стабильную ветку.

**Важные** новые функции должны всегда отправляться в ветку %%(t)master%%, которая содержит предстоящий релиз Laravel.

Если вы не уверены, как квалифицируется ваша функция (важная или незначительная), пожалуйста, обращайтесь к Тейлору Отвеллу на канал %%(t)#laravel-dev%%.

== Слабые места в безопасности ==

Если вы обнаружите уязвимость в безопасности Laravel, пожалуйста, отправьте письмо Тейлору Отвеллу на %%(t)taylorotwell@gmail.com%%. Все уязвимости в безопасности будут оперативно устранены.

== Стиль оформления кода ==

Laravel следует стандартам оформления кода ((https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md PSR-0)) и ((https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md PSR-1)). В дополнение к ним также стоит соблюдать следующие правила:
  * Объявление пространства имён класса должно быть на той же строке, что и %%<?php%%.
  * Открытие класса %%{%% должно быть на той же строке, что и имя класса.
  * Функции и структуры управления должны использовать стиль скобок Оллмана.
  * Отступ - табуляцией, выравнивание - пробелами.