Вклад¶
Настройка¶
Форк на github¶
Прежде чем делать что-либо еще, войдите/зарегистрируйтесь на Github.com и форкните django-crispy-forms с сайта https://github.com/django-crispy-forms/django-crispy-forms.
Клонируйте свой форк локально¶
Если у вас установлен git-scm, теперь вы можете клонировать свою git-репо, используя следующий аргумент командной строки, где <my-github-name> - это имя вашей учетной записи на github:
git clone git@github.com/<my-github-name>/django-crispy-forms.git
Требования к установке¶
Установите зависимости для разработки, cd-нув в папку crispy-forms, а затем выполнив:
pip install -r requirements.txt
Django-crispy-forms поставляется со скриптами git hook. Их можно установить, выполнив:
pre-commit install
Pre-commit теперь будет автоматически запускаться на git-commit и проверять соблюдение руководства по стилю (black, isort & flake8).
Создание тематических веток и генерация запросов на вытягивание¶
Хотя удобно предоставлять полезные фрагменты кода в issue, для вас как разработчика лучше отправлять pull request. При отправке pull request ваш вклад в django-crispy-forms будет учтен Github.
В git лучше всего выделять каждую тему или функцию в «ветвь темы». В то время как отдельные коммиты позволяют вам контролировать внесение небольших индивидуальных изменений в код, ветви - это отличный способ сгруппировать набор коммитов, относящихся к одной функции, или изолировать различные усилия, когда вы работаете над несколькими темами одновременно.
Хотя требуется некоторый опыт, чтобы понять, как правильно разбивать коммиты, тематическая ветка должна быть ограничена одним issue, как представлено в трекере проблем.
Кроме того, поскольку github привязывает и синхронизирует запрос на вытягивание к определенной ветке, это Единственный способ, которым вы можете отправить более одного исправления за один раз. Если вы отправляете pull request из своей основной ветки, вы не можете больше делать коммиты в своей основной ветке без того, чтобы они не были добавлены в pull request.
Для создания ветви темы проще всего использовать удобный аргумент -b к git checkout:
git checkout -b fix-broken-thing
Switched to a new branch 'fix-broken-thing'
Вы должны использовать достаточно многословное имя для своей ветки, чтобы было понятно, о чем идет речь. Теперь вы можете зафиксировать свои изменения и регулярно выполнять слияние с мастером восходящего потока, как описано ниже.
Когда вы будете готовы генерировать запрос на притяжение, либо для предварительного рассмотрения, либо для рассмотрения возможности слияния с проектом, вы должны сначала поднять свою локальную ветку темы обратно на github:
git push origin fix-broken-thing
Теперь, когда вы перейдете к своему форку на github, вы увидите эту ветку в списке на вкладке «Source», где написано «Switch Branches». Перейдите и выберите ветку вашей темы из этого списка, а затем нажмите кнопку «Pull request».
Здесь вы можете добавить комментарий о своем филиале. Если это ответ на отправленную проблему, хорошо бы поместить ссылку на эту проблему в этот первоначальный комментарий. Менеджеры репозитория получат уведомление о вашем запросе на исправление, и он будет рассмотрен (см. ниже о лучших практиках). Обратите внимание, что вы можете продолжать добавлять коммиты в свою тематическую ветку (и отправлять их на github) либо если вы видите, что что-то нужно изменить, либо в ответ на комментарии рецензента. Если рецензент просит внести изменения, вам не нужно закрывать ветку и выпускать ее заново после внесения изменений. Просто внесите изменения локально, отправьте их на github, а затем добавьте комментарий в раздел обсуждения запроса на вытягивание.
Регулярно подтягивайте изменения из восходящего потока в свой форк¶
Над django-crispy-forms работает множество людей. Поэтому очень важно, чтобы вы регулярно переносили изменения из ствола в свой форк. Нет ничего хуже, чем вложить несколько дней напряженной работы в запрос на перенос, а потом получить отказ из-за того, что он слишком сильно отклонился от ствола.
Для внесения изменений в восходящий поток:
git remote add trunk git://github.com/django-crispy-forms/django-crispy-forms.git
git fetch trunk
Проверьте журнал, чтобы убедиться, что изменения действительно нужны, перед слиянием:
git log ..django-crispy-forms/master
Затем объедините изменения, которые вы извлекли:
git merge django-crispy-forms/master
Более подробную информацию см. на сайте http://help.github.com/fork-a-repo/.
Как добиться принятия вашего Pull Request¶
Нам нужны ваши предложения. Но мы также хотим обеспечить стабильный опыт для наших пользователей и сообщества. Следуйте этим правилам, и вы добьетесь успеха без проблем!
Проведите тесты!¶
Прежде чем отправлять заявку, пожалуйста, запустите весь набор тестов django-crispy-forms через:
make test
Если у вас не установлен make, набор тестов также можно запустить через:
pytest --ds=crispy_forms.tests.test_settings --cov=crispy_forms
Первое, что сделают основные коммиттеры, это выполнят эту команду. Любой запрос на внесение изменений, не прошедший этот набор тестов, будет отклонен.
Всегда полезно добавлять тесты!¶
Мы на собственном опыте убедились, что код без тестов не является надежным. Если в вашем запросе есть тесты, у него больше шансов быть включенным. В противном случае ведущий попросит вас написать тесты или поможет вам в этом.
Мы используем py.test.
Кроме того, делайте свои тесты как можно более простыми. Сложные тесты в конечном итоге требуют своих собственных тестов. Мы бы предпочли видеть дублирование утверждений в тестовых методах, а не хитрые утилиты, которые волшебным образом определяют, какие утверждения нужны на конкретном этапе. Помните: Явное лучше неявного.
Не смешивайте изменение кода с очисткой пробельных элементов¶
Если вы измените две строки кода и исправите 200 строк проблем с пробелами в файле, разница в этом запросе будет функционально нечитабельной и будет отклонена. Устранение пробелов должно быть в отдельном запросе.
Ограничьте свои запросы на исправление одним вопросом¶
Запросы на исправление django-crispy-forms должны быть настолько маленькими/атомарными, насколько это возможно. Большие, широкомасштабные изменения в запросе будут отклонены, с комментариями, чтобы изолировать конкретный код в вашем запросе. Некоторые примеры:
Если вы исправляете ошибку в одном классе помощника, не надо «чистить» не связанные с ним помощники. Такая очистка должна проводиться в другом запросе.
Изменение прав доступа к файлу должно происходить в отдельном запросе с явным указанием причин.
Сохраняйте простоту кода!¶
Запомните дзен питона:
>>> python -c 'import this'
Пожалуйста, сохраняйте ваш код настолько чистым и простым, насколько это возможно. Когда мы видим более одной-двух функций/методов, начинающихся с _my_special_function or things like __builtins__.object = str, мы начинаем беспокоиться. Вместо того, чтобы пытаться разобраться в вашей блестящей работе, мы просто отклоним ее и отправим запрос на упрощение.
Более того, нехватка пикселей закончилась. Мы хотим видеть:
helper вместо hpr.
django-crispy-forms вместо dcf
my_function_that_does_things вместо mftdt.