diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 427cacc..bda3b6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,86 +1,67 @@ # Как внести свой вклад -Внесение своего вклада в этот проект ничем не отличается внесения в других -open source проекты на GitHub'e, но есть несколько ключевых моментов, о которых -стоит знать и помнить. +Внесение своего вклада в этот проект ничем не отличается внесения в других open source проекты на GitHub'e, но есть несколько ключевых моментов, о которых стоит знать и помнить. -Все необходимые пакеты для разработки есть в `requirements-dev.txt`. -Установить их можно с помощью следующей команды: -``` +Все необходимые пакеты для разработки есть в `requirements-dev.txt`. Установить их можно с помощью следующей команды: +```shell pip install -r requirements-dev.txt ``` Основные типы вклада: -- добавление новых полей к существующим классам; -- добавление новых классов; +- добавление новых полей к существующим моделям; +- добавление новых моделей; - установка опциональности какого-то поля; - добавление нового метода в `Client` (новый запрос на API); +- добавление нового метода-сокращения в модель; - добавление примера использование в папку [examples](examples). -Ваш вклад может быть более грандиозным. Так, например, можно написать -интеграционные тесты для класса `Client` и всех методов-сокращений в моделях. -Написать тесты для класса запросов. Написать генератор кода для быстрого добавления -новых полей. +Ваш вклад может быть более грандиозным. Так, например, можно написать интеграционные тесты для класса `Client` и всех методов-сокращений в моделях. Написать тесты для класса запросов. Написать генератор кода для быстрого добавления новых полей. ## Pull Requests -PR'ы должны быть сделаны в `dev` ветку. Определённого шаблона оформления -нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым -словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все -проверки GitHub Actions (тесты, проверка стиля кода). +PR'ы должны быть сделаны в `dev` ветку. Определённого шаблона оформления нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все проверки GitHub Actions (тесты, проверка стиля кода). ## Тесты -Для тестирования используется `pytest`. На данный момент отсутствуют -интеграционные тесты. Поэтому всё что сейчас -требутеся — это юнит тесты классов-обёрток и их дополнительных методов -(если имеются), которые не являются сокращениями для методов клиента. +Для тестирования используется `pytest`. На данный момент отсутствуют интеграционные тесты. Поэтому всё что сейчас требуется — это модульные тесты классов-обёрток и их дополнительных методов (если имеются), которые не являются сокращениями для методов клиента. -Тесты модели должны покрывать 5 основных вещей: конструктор, десериализацию -только обязательных полей, десериализацию всех полей, сравнение -объектов модели, десериализацию пустого словаря. По необходимости десериализацию -списка объектов. +Тесты модели должны покрывать 5 основных вещей: конструктор, десериализацию только обязательных полей, десериализацию всех полей, сравнение объектов модели, десериализацию пустого словаря. По необходимости десериализацию списка объектов. Примеры доступны в папке [tests](tests). ## Документация -Для документации используется `Sphinx`. Документация ведется в [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). -К каждому классу и методу должна быть написана документация на русском языке. -Типы каждого значения. По возможности описано предназначение поля. Если -невозможно логически понять из названия — ставим `TODO`. Обязательно отмечаем -какие поля являются опциональными. Пишем заметки по известным значениям полей, -чтобы из контекста догадываться о предназначении. +Для документации используется `Sphinx`. Документация ведется в [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). К каждому классу и методу должна быть написана документация на русском языке. Указаны типы каждого значения. По возможности описано предназначение поля. Если невозможно логически понять из названия или данных — ставим `TODO`. Обязательно отмечаем какие поля являются опциональными. Пишем заметки по известным значениям полей, чтобы из контекста догадываться о предназначении. -Если добавлен новый файл, то не забудьте сгенерировать `.rst` файл -выполнив команду `make gen` в папке `docs` и добавить его в GIT. +Если добавлен новый класс или функция, то не забудьте сгенерировать `.rst` файл выполнив команду `make gen` в папке `docs` и добавить его в GIT. -Чтобы собрать документацию выполните `make html` в папке `docs`. +Чтобы собрать документацию выполните `make html` в папке `docs`. Для отчистки используйте `make clean`. ## Форматирование кода (стиль написания) -В проекте используется `black`. Не забывайте перед публикацией -отформатировать код и проверить его на работоспособность. -Используются одинарные кавычки. Запускайте `black` с конфигом из основной директории: +В проекте используется `black`. Не забывайте перед публикацией отформатировать код и проверить его на работоспособность. Используются одинарные кавычки. Запускайте `black` с конфигом из основной директории: ```shell black --config=black.toml yandex_music ``` +или + +```shell +make black +``` + ## Создание новых моделей -Исходите из логики при помещении модели в определённый пакет. -Добавьте свою модель для короткого импорта в одну из секций `__init__.py` файла -и пропишите название в `__all__`. Обязательно следите за тем, какие поля -присутствуют всегда, а какие нет. По возможности минимизируйте количество -опциональных полей. Не забывайте перечислить поля, по которым можно отличить -один объект от другого в `_id_attrs` (метод `__post_init__`). Экземпляр класса -`Client` передаётся в каждую модель для возможности написания методов-сокращений. -При наличии дополнительных методов у модели не забудьте создать асинхронную версию -метода добавив в название суффикс `_async`. Кроме этого, если у вашей модели -есть метод, например, `download_async()`, то такому методу следует создать -camel case псевдоним (`downloadAsync()`). Для создания псевдонимов существует -генератор. Всё что вам надо сделать это поместить в конце файла с моделью маркер: +Исходите из логики при помещении модели в определённый пакет. Добавьте свою модель для короткого импорта в одну из секций `__init__.py` файла и пропишите название в `__all__`. + +Обязательно следите за тем, какие поля присутствуют всегда, а какие нет. По возможности минимизируйте количество опциональных полей. + +Не забывайте перечислить поля, по которым можно отличить один объект от другого в `_id_attrs` (метод `__post_init__`). + +Экземпляр класса `Client` передаётся в каждую модель для возможности написания методов-сокращений. При наличии дополнительных методов у модели не забудьте создать асинхронную версию метода добавив в название суффикс `_async`. + +Кроме этого, если у вашей модели есть метод, например, `download_async()`, то такому методу следует создать camel case псевдоним (`downloadAsync()`). Для создания псевдонимов существует генератор. Всё что вам надо сделать это поместить в конце файла с моделью маркер: ``` # camelCase псевдонимы @@ -94,8 +75,7 @@ python generate_camel_case_aliases.py ### Создание новых методов клиента -Если ваша задача включает добавление нового API метода, то не забудьте -сгенерировать асинхронную версию клиента. Сделать это можно следующей командой: +Если ваша задача включает добавление нового API метода, то не забудьте сгенерировать асинхронную версию клиента. Сделать это можно следующей командой: ```shell python generate_async_version.py @@ -103,7 +83,9 @@ python generate_async_version.py Ни в коем случае не редактируйте файл `client_async.py` и `request_async.py` руками! -## Для разработчиков на macOS и Linux +## Makefile + +_Используйте WSL если вы на Windows._ Для упрощения жизни в корне проекта существует [Makefile](Makefile). @@ -112,5 +94,4 @@ python generate_async_version.py make all ``` -Выполнит за вас black для основного модуля и тестов, сгенерирует асинхронную -версию клиента, сгенерирует camel case псевдонимы. +Выполнит за вас black для основного модуля и тестов, сгенерирует асинхронную версию клиента, сгенерирует camel case псевдонимы.