Код

Патчи и запросы (patches и pull requests) на контрибуцию - отличный способ внести код обратно в CakePHP. Pull запросы могут быть созданы в GitHub и предпочтительны для файлов патчей и комментариев к билетам.

Начальная настройка

Перед началом работы над исправлениями для CakePHP, хорошей идее является установка и настройка вашей среды. Вам понадобится следующее программное обеспечение:

  • Git
  • PHP 5.6.0 или выше
  • PHPUnit 5.7.0 или выше

Настройте свою пользовательскую информацию с помощью вашего имени/дескриптора и рабочего адреса электронной почты:

git config --global user.name 'Bob Barker'
git config --global user.email 'bob.barker@example.com'

Примечание

Если вы новичок в Git, мы настоятельно рекомендуем вам ознакомиться с превосходной и бесплатной книгой ProGit.

Получите клон исходного кода CakePHP с GitHub:

  • Если вы не имеете аккаунта на GitHub, создайте его.
  • Сделайте fork CakePHP repository, нажав кнопку Fork

После того, как ваш fork сделан, клонируйте его на свою локальную машину:

git clone git@github.com:YOURNAME/cakephp.git

Добавьте исходный репозиторий CakePHP в качестве удаленного репозитория. Вы будете использовать его позже, для извлечения изменений из репозитория CakePHP. Это позволит вам не прозивать любые изменения в главном репозитории CakePHP:

cd cakephp
git remote add upstream git://github.com/cakephp/cakephp.git

Теперь, когда у вас установлен CakePHP, вы должны определить переменную $test database connection, и run all the tests.

Работа над патчем

Каждый раз, когда вы хотите работать над ошибкой, функцией или улучшением, создайте тему ветки.

Ветка, которую вы создаёте, должна основываться на версии, которую вы исправили/улучшили. Например, если вы исправляете ошибку в 3.x, вы должны использовать master в качестве базы для вашей ветки. Если ваше изменение является исправлением ошибки для 2.x, вы должны использовать ветвь 2.x. Это позже делает слияние ваших изменений намного проще, так как Github не позволяет вам редактировать цель ветви:

# fixing a bug on 3.x
git fetch upstream
git checkout -b ticket-1234 upstream/master

# fixing a bug on 2.x
git fetch upstream
git checkout -b ticket-1234 upstream/2.x

Совет

Использовать описательное имя для своей ветки, ссылающееся на билет или имя функции - хорошее правило. Например имя: билет-1234, особенно-хорошее

Вышеупомянутое создаст локальную ветвь, основанную на верхнюю ветку CakePHP 2.x. Поработайте над своим исправлением и сделайте так много коммитов, сколько вам нужно; но имейте в виду следующий:

  • Следуйте Стандарты кодирования.
  • Добавьте тестовый пример, чтобы показать, что ошибка исправлена, или что новая функция работает.
  • Держите свои коммиты логичными и пишите хорошие четкие и сжатые сообщения о фиксации.

Отправка Pull Request

Как только ваши изменения будут выполнены, и вы будете готовы к их объединению с CakePHP, вы должны обновить свою ветку:

# Rebase fix on top of master
git checkout master
git fetch upstream
git merge upstream/master
git checkout <branch_name>
git rebase master

Это приведет к слиянию + объединению при любых изменениях, произошедших в CakePHP, с того момента, как вы начали. Затем он будет перезагружен - или повторите ваши изменения поверх текущего кода. Вы можете столкнуться с конфликтом во время rebase. Если rebase завершит работу раньше, то вы сможете увидеть какие файлы конфликтуются/не объединяются использовав команду git status. Разрешите каждый конфликт, а затем продолжите rebase:

git add <filename> # do this for each conflicted file.
git rebase --continue

Убедитесь, что все ваши тесты продолжают успешно проходить. Затем нажмите(push) для вашего форка:

git push origin <branch-name>

Если вы переустановили, нажав на свою ветку, вам понадобится принудительное нажатие:

git push --force origin <branch-name>

Как только ваша ветвь попадёт в GitHub, вы сможете отправить запрос на выгрузку на GitHub.

Выберите где будут объединены ваши изменения

Перед выполнением pull запросов, вы должны убедиться, что вы выбрали правильную базу, иначе вы не сможете изменить это после создания запроса pull request.

  • Если ваше изменение является исправлением бага и не вводит новые функции и только исправляет существующее поведение, которое присутствует в текущей версии, значит выберите master в качестве цели слияния.
  • Если ваше изменение является новой функцией или дополнением к структуре, то вам следует выбрать ветку со следующим номером версии. Например, если текущая стабильная версия - 3.2.10, то ветвь принимающая новые функции, должна быть 3.next.
  • Если ваше изменение нарушает существующие функциональные возможности или API, тогда вы можете выбрать следующий крупный выпуск. Например, если текущий выпуск 3.2.2, то в следующий раз, когда текущее поведение может не быть нарушено, будет 4.x, поэтому вы должны настроить ссылку на эту ветку.

Примечание

Помните, что весь код, который вы вносите в CakePHP, будет лицензирован в соответствии с лицензией MIT и Cake Software Foundation станет владельцем любого внесенного кода. Авторы должны следовать CakePHP Community Guidelines.

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