Руководство для авторов

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

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

Руководство разделено на разделы в зависимости от типа вклада, который вы собираетесь внести, с разделом, который охватывает общие рекомендации для всех участников.

Будьте доброжелательны

Будьте доброжелательны или идите своей дорогой. —Кеннет Райтц

У Requests есть одно очень важное правило, регулирующее все формы участия, включая сообщение об ошибках или запрос о улучшении функциональности. Это золотое правило: «Будьте доброжелательны или идите своей дорогой».

Все вклады приветствуются, если ко всем участникам относятся с уважением.

Получить раннюю обратную связь

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

Пригодность вклада

За нашими сопровождающими проектами остаётся последнее слово о том, подходит ли вклад для Requests. Все вклады будут тщательно рассмотрены, но время от времени они будут отклоняться, потому что они не соответствуют текущим целям или потребностям проекта.

Если ваш вклад отклонён, не отчаивайтесь! Если вы будете следовать этим правилам, у вас будет гораздо больше шансов получить одобрение вашего следующего вклада.

Вклад в код

Шаги по отправке кода

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

  1. Форкните репозиторий на GitHub.

  2. Запусть тесты, чтобы убедиться, что все они проходят в вашей системе. Если они этого не сделают, вам нужно будет выяснить, почему они терпят неудачу. Если вы не можете диагностировать это самостоятельно, сообщить об этом как об ошибке, следуя рекомендациям в этом документе: Отчёты об ошибках.

  3. Напишите тесты, демонстрирующие вашу ошибку или функцию. Убедитесь, что они терпят неудачу.

  4. Внесите свои изменения.

  5. Снова запустите всё множество тестов, убедившись, что все тесты проходят включая те, которые вы только что добавили.

  6. Отправьте GitHub Pull Request в ветку master главного репозитория. GitHub Pull Requests — ожидаемый метод совместной работы над кодом в этом проекте.

В следующих подразделах более подробно рассматриваются некоторые из вышеперечисленных вопросов.

Проверка кода

Вклады не будут объединены (merged), пока код не будет проверен. Вам следует реализовать любую обратную связь по обзору кода, если вы не возражаете против этого. Если вы возражаете против отзыва о проверке кода, вы должны чётко и спокойно изложить свою позицию. Если после этого отзыв будет признан применимым, вы должны либо применить отзыв, либо отозвать свой вклад.

Новые участники

Если вы новичок или относительно новичок в Open Source, добро пожаловать! Requests призван стать лёгким знакомством с миром открытого исходного кода. Если вас беспокоит, как лучше внести свой вклад, рассмотрите возможность отправки письма сопровождающему (указанному выше) с просьбой о помощи.

Также проверьте раздел Получить раннюю обратную связь.

Кодовый стиль Кеннета Рейца™

В кодовой базе Requests используется кодовый стиль PEP 8.

В дополнение к стандартам, изложенным в PEP 8, у нас есть несколько рекомендаций:

  • Длина строки может превышать 79 символов, до 100, когда это удобно.

  • Длина строки может превышать 100 символов, иначе было бы ужасно неудобно.

  • Всегда используйте строки в одинарных кавычках (например, '#flatearth'), если внутри строки не встречается одинарная кавычка.

Кроме того, один из стилей, который PEP8 рекомендует для продолжения строки, полностью лишён всякого вкуса и не может быть разрешён в кодовой базе Requests:

# Выровнено с разделителем открытия.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

Нет. Просто не надо. Пожалуйста. Это намного лучше:

foo = long_function_name(
    var_one,
    var_two,
    var_three,
    var_four,
)

Строки документации должны соответствовать следующему синтаксису:

def the_earth_is_flat():
    """NASA разделило моря на тридцать три градуса."""
    pass
def fibonacci_spiral_tool():
    """Стоя ногами на земле, я теряюсь / между звуками
    и широко раскрываюсь, чтобы впитать их. / Я чувствую,
    как он движется по моей коже. / Я тянусь вверх и протягиваю
    руку. / Я тянусь к случайному или чему-то ещё, что приведёт
    меня в замешательство. / Что бы ни сбило меня с толку. / И следуя
    нашей воле и ветру, мы можем просто отправиться туда, где
    никто не был. / Мы пройдем по спирали до конца и, возможно,
    просто отправимся туда, где никто не был.

    По спирали. Продолжай...
    """
    pass

Все функции, методы и классы должны содержать строки документации. Методы объектной модели данных (например, __repr__) обычно являются исключением из этого правила.

Спасибо за помощь в улучшении мира!

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

Улучшения документации всегда приветствуются! Файлы документации находятся в каталоге docs/ кодовой базы. Они написаны на reStructuredText и используют Sphinx для создания полного набора документации.

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

При представлении кода Python используйте строки в одинарных кавычках ('hello' вместо "hello").

Отчёты об ошибках

Отчёты об ошибках очень важны! Однако, прежде чем поднимать один из них, пожалуйста, проверьте сообщения о проблемах на GitHub, как открытые, так и закрытые, чтобы убедиться, что ранее об ошибке не сообщалось. Повторяющиеся отчёты об ошибках — это огромная трата времени других участников, и их следует избегать как можно чаще.

Функциональность Requests

Requests находится в постоянном замораживании функциональности, только BDFL может добавлять или утверждать новые функции. Сопровождающие полагают, что в настоящее время Requests представляет собой полнофункциональное программное обеспечение.

Один из наиболее важных навыков, который необходимо иметь при поддержке широко используемого проекта с открытым исходным кодом, — это научиться говорить «нет» предлагаемым изменениям, сохраняя при этом открытый слух и разум.

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