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

CodeIgniter — это проект, управляемый сообществом, который принимает вклады от членов сообщества в виде кода и документации. Эти вклады делаются в форме проблем (issues) или пулл-запросов (pull requests) на репозиторий CodeIgniter.

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

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

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

Правила

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

Все код должен соответствовать стилю оформления, который представляет собой стиль оформления Allman с отступами, нижним подчеркиванием и понятными операторами. Это гарантирует, что весь код будет иметь одинаковый формат существующего кода и будет максимально удобочитаемым.

Документация

Если вы меняете что-либо, требующее изменения в документации, то вам также потребуется добавить эти изменения. Новые классы, методы, параметры, изменение значений по умолчанию и прочие изменения должны быть отражены в документации. Также журнал изменений должен быть обновлен для каждого изменения. Кроме того, блоки PHPDoc должны быть поддержаны.

Совместимость

CodeIgniter рекомендует использовать PHP 5.4 или более позднюю версию, но он должен быть совместим с PHP 5.2.4, поэтому все предоставляемый код должен соответствовать этому требованию. Если используются функции или возможности PHP 5.3 (и выше), то должно быть предусмотрено альтернативное решение для PHP 5.2.4.### Ветвление CodeIgniter использует модель ветвления Git-Flow, которая требует отправлять все запросы на слияние в ветку "develop". Это место, где будет развиваться следующий запланированный выпуск. Ветка "master" всегда содержит последнюю стабильную версию и поддерживается чистой, чтобы можно было применять "hotfix" (например, экстренный пакет безопасности) к ветке master для создания новой версии, не беспокоясь о других функциях, которые могут этому препятствовать. По этой причине все коммиты должны выполняться в ветке "develop", а любые коммиты в ветку "master" будут автоматически закрываться. Если у вас есть несколько изменений для отправки, пожалуйста, поместите все изменения в свои собственные ветки на вашем форке. Один шаг за раз: В одном запросе на вытягивание (pull request) должно быть только одно изменение. Это не означает, что в нем может быть только один коммит, а именно одно изменение — независимо от того, сколько коммитов потребовалось для его выполнения. Причина этого заключается в том, что если вы меняете X и Y, но отправляете запрос на вытягивание для обоих одновременно, мы можем действительно хотеть X, но не согласиться с Y, что делает невозможной слияние запроса. Используя модель управления версиями Git-Flow, вы можете создать новые ветки для этих двух возможностей и отправить два запроса.### Подпись

Вы должны подписывать вашу работу, свидетельствуя о том, что либо вы сами её написали, либо имеете право передать её в открытый проект. Git делает это простым путём, так как вам просто нужно использовать --signoff при ваших коммитах в форк CodeIgniter.

git commit --signoff

или просто

git commit -s

Это подпишет ваши коммиты информацией, настроенной в вашем конфигурационном файле Git, например:

Signed-off-by: Иван Иванов <ivanov@example.com>

Если вы используете Tower, есть флажок "Подписать" в окне коммита. Вы даже можете создать псевдоним для команды 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. Отправьте вашу ветку develop в ваш форк
9. Отправьте запрос на слияние http://help.github.com/send-pull-requests/ Инженеры Реактора теперь будут проинформированы о внесённых изменениях, и хотя бы один член команды ответит. Если ваши изменения не соответствуют указанным рекомендациям, они будут отклонены, либо вам будет предоставлена обратная связь для улучшения ваших изменений.

Как только Инженер Реактора, занимающийся вашим запросом на слияние, одобрит его, он сольёт изменения в ветку develop, и ваш патч станет частью следующего выпуска.### Поддержание актуальности вашего форка

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

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

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

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