yandex-music-api/CONTRIBUTING.md

117 行
7.4 KiB
Markdown
Raw 通常表示 履歴

# Как внести свой вклад
Внесение своего вклада в этот проект ничем не отличается внесения в других
open source проекты на GitHub'e, но есть несколько ключевых моментов, о которых
стоит знать и помнить.
2022-02-16 19:53:09 +09:00
Все необходимые пакеты для разработки есть в `requirements-dev.txt`.
Установить их можно с помощью следующей команды:
```
2022-02-16 19:53:09 +09:00
pip install -r requirements-dev.txt
```
Основные типы вклада:
- добавление новых полей к существующим классам;
- добавление новых классов;
- установка опциональности какого-то поля;
- добавление нового метода в `Client` (новый запрос на API);
- добавление примера использование в папку [examples](examples).
Ваш вклад может быть более грандиозным. Так, например, можно написать
интеграционные тесты для класса `Client` и всех методов-сокращений в моделях.
2022-02-16 19:53:09 +09:00
Написать тесты для класса запросов. Написать генератор кода для быстрого добавления
новых полей.
## Pull Requests
2022-02-16 19:53:09 +09:00
PR'ы должны быть сделаны в `dev` ветку. Определённого шаблона оформления
нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым
словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все
проверки GitHub Actions (тесты, проверка стиля кода).
## Тесты
Для тестирования используется `pytest`. На данный момент отсутствуют
интеграционные тесты. Поэтому всё что сейчас
требутеся — это юнит тесты классов-обёрток и их дополнительных методов
(если имеются), которые не являются сокращениями для методов клиента.
Тесты модели должны покрывать 5 основных вещей: конструктор, десериализацию
только обязательных полей, десериализацию всех полей, сравнение
объектов модели, десериализацию пустого словаря. По необходимости десериализацию
списка объектов.
Примеры доступны в папке [tests](tests).
## Документация
Для документации используется `Sphinx`. Документация ведется в [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
К каждому классу и методу должна быть написана документация на русском языке.
Типы каждого значения. По возможности описано предназначение поля. Если
2022-02-16 19:53:09 +09:00
невозможно логически понять из названия — ставим `TODO`. Обязательно отмечаем
какие поля являются опциональными. Пишем заметки по известным значениям полей,
чтобы из контекста догадываться о предназначении.
Если добавлен новый файл, то не забудьте сгенерировать `.rst` файл
выполнив команду `make gen` в папке `docs` и добавить его в GIT.
Чтобы собрать документацию выполните `make html` в папке `docs`.
## Форматирование кода (стиль написания)
В проекте используется `black`. Не забывайте перед публикацией
отформатировать код и проверить его на работоспособность.
2022-10-17 00:22:42 +09:00
Используются одинарные кавычки. Запускайте `black` с конфигом из основной директории:
```shell
black --config=black.toml yandex_music
```
## Создание новых моделей
Исходите из логики при помещении модели в определённый пакет.
Добавьте свою модель для короткого импорта в одну из секций `__init__.py` файла
и пропишите название в `__all__`. Обязательно следите за тем, какие поля
присутствуют всегда, а какие нет. По возможности минимизируйте количество
опциональных полей. Не забывайте перечислить поля, по которым можно отличить
2022-02-16 19:53:09 +09:00
один объект от другого в `_id_attrs` (метод `__post_init__`). Экземпляр класса
`Client` передаётся в каждую модель для возможности написания методов-сокращений.
2022-10-17 00:22:42 +09:00
При наличии дополнительных методов у модели не забудьте создать асинхронную версию
метода добавив в название суффикс `_async`. Кроме этого, если у вашей модели
есть метод, например, `download_async()`, то такому методу следует создать
camel case псевдоним (`downloadAsync()`). Для создания псевдонимов существует
генератор. Всё что вам надо сделать это поместить в конце файла с моделью маркер:
```
# camelCase псевдонимы
```
([пример](https://github.com/MarshalX/yandex-music-api/blob/a30082f4929e56381c870cb03103777ae29bcc6b/yandex_music/tracks_list.py#L80))
После чего запустить генератор:
```shell
python generate_camel_case_aliases.py
```
### Создание новых методов клиента
Если ваша задача включает добавление нового API метода, то не забудьте
сгенерировать асинхронную версию клиента. Сделать это можно следующей командой:
```shell
python generate_async_version.py
```
Ни в коем случае не редактируйте файл `client_async.py` и `request_async.py` руками!
## Для разработчиков на macOS и Linux
Для упрощения жизни в корне проекта существует [Makefile](Makefile).
Команда
```shell
make all
```
Выполнит за вас black для основного модуля и тестов, сгенерирует асинхронную
версию клиента, сгенерирует camel case псевдонимы.