Как вносить свой вклад в исходный код

Этот документ представляет собой описание состава команды ThinkPHP и механизма её работы, какие преимущества принесут ваши изменения проекту ThinkPHP и как вы можете присоединиться к нам.

Внесение пулл-запросов через GitHub

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

Процесс участия довольно прост:

1. Создайте форк ThinkPHP в вашем репозитории;
2. Измените код;
3. Отправьте pull-request;

Мы будем своевременно проверять ваш запрос и принимать решение о его одобрении. После успешной проверки ваш код будет объединён с нашей основной веткой, что автоматически добавит вас в список вкладчиков.

Мы надеемся, что ваш вклад будет соответствовать следующим требованиям:

• Кодификационным нормам ThinkPHP
• Принципам документирования, чтобы другие могли понять код
• Лицензии Apache2

Дополнительная информация доступна ниже

Учебные материалы

• Проект использует стандарт форматирования кода PER-CS2.0;
• Названия классов и файлов классов должны соответствовать PSR-4;
• Для закрытия задач (Issues) используйте названия коммитов вида fix #xxx(идентификатор задачи);
• Автоматическое тестирование производится на версиях PHP от 8.0 до 8.3, убедитесь, что ваши изменения соответствуют этим версиям;
• Администраторы не будут объединять изменения, вызывающие провал CI, если это произошло, проверьте свой код или соответствующие файлы юнит-тестов.

GitHub Issues

Функционал GitHub Issues можно использовать для:

• Предложения багов
• Предложений по улучшению функциональности
• Обратной связи по использованию

Эта функция не должна использоваться для:

• Предложения конкретных изменений (включает вопросы авторства и отслеживания изменений)
• Оскорбительных высказываний

Быстрое редактирование

GitHub предоставляет возможность быстрого редактирования файлов

1. Авторизуйтесь в системе GitHub;
2. Перейдите к файлам проекта и найдите нужный вам файл;
3. Нажмите значок карандаша в правом верхнем углу для начала редактирования;
4. Введите необходимую информацию для коммита (обязательно название);
5. Сохраните изменения и подождите завершение CI-тестирования и объединения администратором.

Если требуется внести множество изменений, продолжайте чтение ниже

Полный процесс

1. Создайте форк этого проекта;
2. Клонируйте форкнутый проект на локальную машину;
3. Создайте новую ветку и переключитесь на неё;
4. Добавьте этот проект в ваш локальный репозиторий Git как upstream;
5. Внесите изменения, если они включают добавление или удаление методов или функций, не забудьте также внести изменения в файлы юнит-тестов;
6. Выполните rebasing вашей ветки на upstream master;
7. Отправьте вашу локальную ветку на GitHub;
8. Отправьте pull-request;
9. Подождите завершение CI-тестирования (если он провалился, повторите шаги 5-7, GitHub автоматически обновит ваш pull-request);
10. Подождите решения администратора и выполните rebasing вашей ветки на upstream master (если upstream master был изменён).

Если необходимо, вы можете использовать git push -f для отправки rebased ветки на свой fork.

Никогда не используйте git push -f для отправки изменений на upstream.

Учебные материалы

• Если вы не уверены в процессе, обратитесь к учебникам по Git, таким как этот;
• Для различных типов изменений создавайте различные ветки в своем форке (причины указаны в примечании к шагу 9 полного процесса);
• Информация о rebasing и interactive rebasing доступна здесь Git Interactive Rebase;

Рекомендованные ресурсы

Разработка окружения

• XAMPP - Windows, Linux, MacOS
• WampServer - Windows
• Docker - Windows, Linux, MacOS

или установите самостоятельно:

• Apache/Nginx
• PHP 8.0 - 8.3
• MySQL/MariaDB

Рекомендуется пользователям Windows добавить директорию bin PHP в PATH для удобства использования Composer Любители Linux могут настроить среду самостоятельно, а пользователи MacOS могут использовать встроенную Apache вместе с Homebrew для установки PHP и MariaDB

Редакторы кода

Sublime Text 3 + плагин phpfmt

Параметры плагина phpfmt

{
    "autocomplete": true,
    "enable_auto_align": true,
    "format_on_save": true,
    "indent_with_space": true,
    "psr1_naming": false,
    "psr2": true,
    "version": 4
}

или другой редактор/IDE совместно с автозагрузкой

Интерфейсы графического представления Git

• SourceTree
• GitHub Desktop

или другой клиент Git с графическим интерфейсом