Вклад в разработку REST-фреймворка¶
Мир можно изменить только по кусочку за раз. Искусство заключается в том, чтобы выбрать этот кусочек.
‒ Tim Berners-Lee
Есть много способов, которыми вы можете внести свой вклад в развитие фреймворка Django REST. Мы хотим, чтобы это был проект, управляемый сообществом, поэтому, пожалуйста, участвуйте и помогайте формировать будущее проекта.
Сообщество¶
Самое важное, что вы можете сделать, чтобы помочь проекту REST framework продвинуться вперед, - это активно участвовать во всех возможных проектах. Вклад в код часто переоценивается как основной способ участия в проекте, но мы не считаем, что так должно быть.
Если вы используете фреймворк REST, мы будем рады, если вы расскажете о своем опыте работы с ним - вы можете написать статью в блоге об использовании фреймворка REST или опубликовать учебник по созданию проекта с использованием определенного фреймворка JavaScript. Опыт новичков может быть особенно полезен, поскольку вы сможете лучше оценить, какие части REST-фреймворка сложнее понять и с чем работать.
Другие действительно хорошие способы, которыми вы можете помочь продвижению сообщества, включают помощь в ответах на вопросы на discussion group <https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework>`_** , или установку :doc:`email alert on StackOverflow <https://stackexchange.com/filters/66475/rest-framework>, чтобы вы получали уведомления о новых вопросах с помощью тега django-rest-framework.
Отвечая на вопросы, обязательно помогите будущим участникам найти нужную информацию, по возможности делая гиперссылки на связанные темы и тикеты, и, если это уместно, включайте обратные ссылки с этих тем.
Кодекс поведения¶
Пожалуйста, сохраняйте вежливый и профессиональный тон. Для некоторых пользователей обсуждение в списке рассылки или тикет-трекере фреймворка REST может стать их первым взаимодействием с сообществом разработчиков открытого кода. Первое впечатление имеет значение, поэтому давайте постараемся сделать так, чтобы каждый почувствовал себя желанным гостем.
Будьте осторожны в выборе языка. Например, в среде, где преобладают мужчины, сообщения, начинающиеся со слов «Привет, ребята», могут показаться непреднамеренно эксклюзивными. В таких ситуациях проще и более инклюзивно использовать гендерно нейтральный язык.
В Django code of conduct приводится более полный набор рекомендаций по участию в форумах сообщества.
Вопросы¶
Это будет очень полезно, если вы сможете убедиться, что обращаетесь с вопросами по нужному каналу. Вопросы по использованию следует направлять в канал discussion group. Запросы о возможностях, отчеты об ошибках и другие вопросы следует задавать на GitHub issue tracker.
Несколько советов по правильному освещению проблемы:
При описании проблем постарайтесь сформулировать свой тикет в терминах поведения, которое, по вашему мнению, нужно изменить, а не кода, который, по вашему мнению, нужно изменить.
Сначала найдите в списке проблем связанные с ними вопросы и убедитесь, что у вас установлена последняя версия REST framework, прежде чем сообщать о проблеме.
Если вы сообщаете об ошибке, то постарайтесь приложить к ней запрос на выгрузку с неудачным тестовым примером. Это поможет нам быстро определить, есть ли проблема, и убедиться, что она будет исправлена быстрее, если она есть.
Запросы на функции часто закрываются с рекомендацией реализовать их вне основной библиотеки фреймворка REST. Реализация запросов на новые возможности в виде сторонних библиотек позволяет нам снизить затраты на обслуживание фреймворка REST, чтобы сосредоточиться на стабильности, исправлении ошибок и отличной документации.
Закрытие вопроса не обязательно означает конец обсуждения. Если вы считаете, что ваш вопрос был закрыт неправильно, объясните причину, и мы рассмотрим, нужно ли его снова открыть.
Устранение проблем¶
Участие в сортировке поступающих проблем - хороший способ начать вносить свой вклад. Каждый билет, поступающий в тикет-трекер, должен быть рассмотрен, чтобы определить дальнейшие шаги. Любой может помочь в этом, вам просто нужно быть готовым к тому, чтобы
Прочитайте билет - имеет ли он смысл, нет ли в нем контекста, который помог бы лучше его объяснить?
Помещен ли тикет в правильное место, может быть, лучше было бы обсудить его в дискуссионной группе?
Если билет - это отчет об ошибке, можете ли вы воспроизвести ее? Можете ли вы написать неудачный тестовый пример, который демонстрирует проблему и который можно отправить в качестве запроса на исправление?
Если тикет - это запрос функции, согласны ли вы с ним, и можно ли вместо этого реализовать запрос функции в виде стороннего пакета?
Если в билете не было большой активности, а в нем рассматривается что-то нужное вам, то прокомментируйте билет и постарайтесь выяснить, что нужно для того, чтобы он снова заработал.
Разработка¶
Чтобы начать разработку на фреймворке Django REST, сначала создайте форк из Django REST Framework repo на GitHub.
Затем клонируйте свой форк. Команда clone будет выглядеть следующим образом, с вашим именем пользователя GitHub вместо YOUR-USERNAME:
git clone https://github.com/YOUR-USERNAME/django-rest-framework
Для получения дополнительной информации см. руководство GitHub ** *Fork a Repo*.
Изменения должны в целом соответствовать стилевым соглашениям PEP 8, и мы рекомендуем вам настроить ваш редактор на автоматическое указание несоответствующих стилей. Вы можете проверять свой вклад на соответствие этим соглашениям при каждой фиксации с помощью хуков pre-commit, которые мы также запускаем на CI. Чтобы настроить их, сначала убедитесь, что у вас установлен инструмент pre-commit, например:
python -m pip install pre-commit
Тогда бегите:
pre-commit install
Тестирование¶
Чтобы запустить тесты, клонируйте репозиторий, а затем:
# Setup the virtual environment
python3 -m venv env
source env/bin/activate
pip install django
pip install -r requirements.txt
# Run the tests
./runtests.py
Варианты испытаний¶
Запуск с использованием более лаконичного стиля вывода.
./runtests.py -q
Запуск тестов для данного тестового случая.
./runtests.py MyTestCase
Выполните тесты для данного метода тестирования.
./runtests.py MyTestCase.test_this_method
Более короткая форма для запуска тестов для данного метода тестирования.
./runtests.py test_this_method
Примечание: Сопоставление тестового случая и метода тестирования является нечетким и иногда запускает другие тесты, которые содержат частичное совпадение строк с заданным вводом командной строки.
Выполнение в нескольких средах¶
Вы также можете использовать превосходный инструмент тестирования tox для запуска тестов на всех поддерживаемых версиях Python и Django. Установите tox глобально, а затем просто запустите:
tox
Pull requests¶
Хорошей идеей является раннее составление запросов на исправление. Запрос на исправление представляет собой начало обсуждения и не обязательно должен быть окончательным, готовым представлением.
Также всегда лучше создавать новую ветку перед началом работы над запросом на исправление. Это означает, что впоследствии вы сможете вернуться к работе над другим отдельным вопросом, не вмешиваясь в текущий запрос.
Также полезно помнить, что если у вас есть невыполненные запросы на вытягивание, то размещение новых коммитов в вашем репозитории GitHub также автоматически обновит запросы на вытягивание.
Документация GitHub по работе над pull request’ами - available here.
Всегда запускайте тесты перед отправкой запросов на перенос, а в идеале запускайте tox, чтобы проверить, что ваши модификации совместимы на всех поддерживаемых версиях Python и Django.
После того, как вы сделали запрос на перенос, посмотрите на статус сборки в интерфейсе GitHub и убедитесь, что тесты выполняются так, как вы ожидали.
Вверху: уведомления о строительстве
Управление проблемами совместимости¶
Иногда, для того чтобы ваш код работал на различных версиях Django, Python или сторонних библиотек, вам нужно будет запускать немного разный код в зависимости от окружения. Любой код, который ветвится таким образом, должен быть изолирован в модуль compat.py, и должен предоставлять один общий интерфейс, который может использовать остальная часть кодовой базы.
Документация¶
Документация для REST framework построена на основе исходных файлов Markdown в the docs directory.
Существует множество отличных редакторов Markdown, которые делают работу с документацией очень простой. Mou editor for Mac - один из таких редакторов, который очень рекомендуется.
Создание документации¶
Чтобы собрать документацию, установите MkDocs с помощью pip install mkdocs, а затем выполните следующую команду.
mkdocs build
Это позволит собрать документацию в каталог site.
Вы можете собрать документацию и открыть предварительный просмотр в окне браузера с помощью команды serve.
mkdocs serve
Стиль языка¶
Документация должна быть составлена на американском английском языке. Тон документации очень важен - по возможности старайтесь придерживаться простого, понятного, объективного и сбалансированного стиля.
Некоторые другие советы:
Делайте абзацы достаточно короткими.
Не используйте сокращений, таких как «например», вместо этого используйте длинную форму, например, «Например».
Стиль разметки¶
Существует несколько условностей, которых следует придерживаться при работе над документацией.
В заголовках следует использовать стиль хэш. Например:
### Some important topic
Не следует использовать стиль подчеркивания. Не делайте этого:.
Some important topic
====================
В ссылках всегда должен использоваться стиль ссылок, при этом гиперссылки должны располагаться в конце документа.
Here is a link to [some other thing][other-thing].
More text...
[other-thing]: http://example.com/other/thing
Этот стиль помогает сохранить последовательность и читабельность источника документации.
Если вы ставите гиперссылку на другой документ REST framework, вы должны использовать относительную ссылку и ссылаться на суффикс .md. Например:
[authentication]: ../api-guide/authentication.md
Ссылка в этом стиле означает, что вы сможете нажать на гиперссылку в редакторе Markdown, чтобы открыть документ, на который ссылаетесь. Когда документация будет создана, эти ссылки будут преобразованы в обычные ссылки на HTML-страницы.
Если вы хотите привлечь внимание к примечанию или предупреждению, используйте пару заключающих линий, как показано ниже:
---
**Note:** A useful documentation note.
---