From c0dc65875d05459b7abfa779ba05c7a7c90e63e7 Mon Sep 17 00:00:00 2001 From: Il`ya Semyonov Date: Thu, 4 Feb 2021 12:53:43 +0100 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=20=D0=B8=D0=BD=D1=84=D0=BE=D1=80=D0=BC=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D0=B2=D0=BD=D0=B5=D1=81=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D1=8E=20=D1=81=D0=B2=D0=BE=D0=B5=D0=B3=D0=BE=20?= =?UTF-8?q?=D0=B2=D0=BA=D0=BB=D0=B0=D0=B4=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 12 +++++++++ 2 files changed, 82 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ba89e4b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,70 @@ +# Как внести свой вклад + +Внесение своего вклада в этот проект ничем не отличается внесения в других +open source проекты на GitHub'e, но есть несколько ключевых моментов, о которых +стоит знать и помнить. + +Все необходимые пакеты для разработки есть в dev секции файла с зависимостями. +Установить их можно с помощью следующей команды: +``` +pipenv install --dev +``` + +Основные типы вклада: +- добавление новых полей к существующим классам; +- добавление новых классов; +- установка опциональности какого-то поля; +- добавление нового метода в `Client` (новый запрос на API); +- добавление примера использование в папку [examples](examples). + +Ваш вклад может быть более грандиозным. Так, например, можно написать +интеграционные тесты для класса `Client` и всех методов-сокращений в моделях. +Написать тесты для класса запросов. Переписать модели с некрасивых конструкторов +на `Pydantic` или что-нибудь ещё. Написать генератор кода для быстрого добавления +новых полей. + +## Pull Requests + +PR'ы должны быть сделаны в `development` ветку. Определённого шаблона оформления +нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым +словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все +проверки GitHub Actions (тесты, проверка стиля кода). + +## Тесты + +Для тестирования используется `pytest`. На данный момент отсутствуют +интеграционные тесты. Поэтому всё что сейчас +требутеся — это юнит тесты классов-обёрток и их дополнительных методов +(если имеются), которые не являются сокращениями для методов клиента. + +Тесты модели должны покрывать 5 основных вещей: конструктор, десериализацию +только обязательных полей, десериализацию всех полей, сравнение +объектов модели, десериализацию пустого словаря. По необходимости десериализацию +списка объектов. + +Примеры доступны в папке [tests](tests). + +## Документация + +Для документации используется `Sphinx`. Документация ведется в [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). +К каждому классу и методу должна быть написана документация на русском языке. +Типы каждого значения. По возможности описано предназначение поля. Если +невозможно понять — ставим `TODO`. Обязательно отмечаем какие поля являются +опциональными. Пишем заметки по известным значениям полей, чтобы из контекста +догадываться о предназначении. + +Если добавлен новый класс, то не забудьте создать `.rst` файл в папке +[docs/source](docs/source) и добавить его в дерево нужного пакета. + +## Форматирование кода (стиль написания) + +В проекте используется `black`. Не забывайте перед публикацией +отформатировать код и проверить его на работоспособность. + +## Создание новых моделей + +Исходите из логики при помещении модели в определённый пакет. +Добавьте свою модель для короткого импорта в одну из секций `__init__.py` файла +и пропишите название в `__all__`. Обязательно следите за тем, какие поля +присутствуют всегда, а какие нет. По возможности минимизируйте количество +опциональных полей. diff --git a/README.rst b/README.rst index be342fe..645767e 100644 --- a/README.rst +++ b/README.rst @@ -75,6 +75,8 @@ API Yandex Music - неофициальная Python библиотека - `Благодарность`_ +- `Внесение своего вклада в проект`_ + - `Лицензия`_ ======== @@ -372,6 +374,16 @@ Telegram бот-клиент Спасибо разработчикам ``python-telegram-bot``. Выбрал Вас в качестве примера. +=============================== +Внесение своего вклада в проект +=============================== + +Внесение своего вклада максимально приветствуется! Есть перечень пунктов, +который стоит соблюдать. Каждый пункт перечня расписан в `CONTRIBUTING `_. + +Вы можете помочь и сообщив о `баге `_ +или о `новом поле пришедшем от API `_. + ======== Лицензия ========