Внесение вклада в CodeIgniter

CodeIgniter — это проект, который развивается сообществом, и он принимает вклады кода и документации от сообщества. Эти вклады делаются в виде задач или запросов на вытягивание (Pull Requests) в репозитории CodeIgniter на GitHub.

Задачи — это быстрый способ указать на ошибку. Если вы обнаружите ошибку или ошибку в документации в CodeIgniter, пожалуйста, сначала проверьте следующее:

1. Нет ли уже открытой задачи?
2. Была ли эта проблема уже исправлена (проверьте ветку разработки или поищите закрытые задачи)?
3. Это что-то действительно очевидное, что вы можете исправить сами?

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

Рекомендации

Прежде чем мы рассмотрим, как это сделать, вот рекомендации. Если ваши запросы на вытягивание не соответствуют этим рекомендациям, они будут отклонены, и вам нужно будет повторно отправить их после внесения изменений. Это может показаться немного сложным, но это необходимо для поддержания качества кодовой базы.

• Стиль PHP: весь код должен соответствовать руководству по стилю (Style Guide), которое по сути является стилем отступа Allman, подчёркиваниями и читаемыми операторами. Это гарантирует, что весь код имеет тот же формат, что и существующий код, и означает, что он будет максимально читаемым.
• Документация: если вы изменяете что-либо, требующее изменения документации, вам необходимо добавить это. Новые классы, методы, параметры, изменение значений по умолчанию и т. д. — всё это требует изменения документации. Журнал изменений также должен обновляться при каждом изменении. Также необходимо поддерживать блоки PHPDoc.
• Совместимость: CodeIgniter рекомендует использовать PHP 5.4 или более новую версию, но он должен быть совместим с PHP 5.2.4, поэтому весь предоставленный код должен соответствовать этому требованию. Если используются функции или возможности PHP 5.3 (и выше), то должен существовать запасной вариант для PHP 5.2.4.
• Ветвление: CodeIgniter использует модель ветвления Git-Flow, которая требует, чтобы все запросы на вытягивание отправлялись в ветку «develop». Именно здесь будет разрабатываться следующая запланированная версия. Ветка «master» всегда будет содержать последнюю стабильную версию и поддерживается чистой, так что исправление (например, экстренное исправление безопасности) может быть применено к мастеру для создания новой версии без беспокойства о других функциях, задерживающих её. По этой причине все коммиты должны быть сделаны в «develop», а любые отправленные в «master» будут автоматически закрыты. Если у вас есть несколько изменений для отправки, пожалуйста, поместите все изменения в свою собственную ветку на вашем форке.
• По одному изменению за раз: запрос на вытягивание должен содержать только одно изменение. Это не означает только один коммит, но одно изменение — независимо от того, сколько коммитов потребовалось. Причина этого заключается в том, что если вы измените X и Y, но отправите запрос на вытягивание для обоих одновременно, мы можем действительно захотеть X, но не согласиться с Y, что означает, что мы не сможем объединить запрос. Используя модель ветвления Git-Flow, вы можете создать новые ветки для обеих этих функций и отправить два запроса.
• Подписание: вы должны подписать свою работу, подтверждая, что либо вы написали эту работу, либо имеете право передать её в открытый исходный проект. git делает это тривиальным, поскольку вам просто нужно использовать --signoff в своих коммитах в своём форке CodeIgniter.
  • git commit --signoff или просто
  • git commit -s

Это подпишет ваши коммиты информацией, настроенной в вашем git config, например:

`Signed-off-by: John Q Public <john.public@example.com>`

Если вы используете Tower, в окне фиксации есть флажок «Sign-Off». Вы даже можете настроить псевдоним git commit для использования флага -s, чтобы вам не приходилось об этом думать.

Подписывая свою работу таким образом, вы подтверждаете «Сертификат разработчика о происхождении». Текущая версия этого сертификата находится в... DCO.txt файл в корне этого репозитория.

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

Есть два способа внести изменения: простой способ и сложный способ. В любом случае вам нужно будет создать учетную запись GitHub.

Простой способ GitHub позволяет редактировать файлы в строке для внесения простых изменений и быстрого исправления ошибок. Это не лучший способ, так как вы не можете проверить, работает ли код. Если вы сделаете это, вы можете допустить синтаксические ошибки и т. д., но для пользователя, который боится Git, это хорошо для быстрого исправления.

Сложный способ Лучший способ внести свой вклад — «клонировать» свою копию CodeIgniter в область разработки. Это звучит как какой-то жаргон, но «форк» на GitHub означает «сделать копию этого репо в вашей учетной записи», а «клонирование» означает «скопировать этот код в вашу среду, чтобы вы могли работать над ним».

1. Установите Git (Windows, Mac & Linux).
2. Перейдите в репозиторий CodeIgniter.
3. Форкните его.
4. Клонируйте свой репозиторий CodeIgniter: git@github.com:/CodeIgniter.git.
5. Проверьте ветку «develop». На этом этапе вы готовы начать вносить изменения.
6. Исправьте существующие ошибки в системе отслеживания проблем, предварительно посмотрев, не работает ли над ними кто-нибудь еще.
7. Зафиксируйте файлы.
8. Отправьте свою ветку разработки в свой форк.
9. Отправьте запрос на вытягивание http://help.github.com/send-pull-requests/.

Теперь инженеры Reactor будут предупреждены об изменении, и по крайней мере один из членов команды ответит. Если ваше изменение не соответствует рекомендациям, оно будет отклонено или будет предоставлена обратная связь, которая поможет вам улучшить его.

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

Поддержание актуальности вашего форка

В отличие от таких систем, как Subversion, Git может иметь несколько удаленных серверов. Удаленный сервер — это имя URL-адреса репозитория Git. По умолчанию ваш форк будет иметь удаленный сервер с именем «origin», который указывает на ваш форк, но вы можете добавить еще один удаленный сервер с именем «codeigniter», который указывает на git://github.com/bcit-ci/CodeIgniter.git. Это доступный только для чтения удаленный сервер, но вы можете извлечь из этой ветки разработки, чтобы обновить свою собственную.

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

1. git remote add codeigniter git://github.com/bcit-ci/CodeIgniter.git
2. git pull codeigniter develop
3. git push origin develop

Теперь ваш форк обновлен. Это следует делать регулярно или, по крайней мере, перед отправкой запроса на вытягивание.