обновлён CONTRIBUTING.md

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` ветку. Определённого шаблона оформления
+PR'ы должны быть сделаны в `dev` ветку. Определённого шаблона оформления нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все проверки GitHub Actions (тесты, проверка стиля кода).
-нет. Если это закрывает какое-то 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).
+Для документации используется `Sphinx`. Документация ведется в [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). К каждому классу и методу должна быть написана документация на русском языке. Указаны типы каждого значения. По возможности описано предназначение поля. Если невозможно логически понять из названия или данных — ставим `TODO`. Обязательно отмечаем какие поля являются опциональными. Пишем заметки по известным значениям полей, чтобы из контекста догадываться о предназначении.
-К каждому классу и методу должна быть написана документация на русском языке. 
-Типы каждого значения. По возможности описано предназначение поля. Если 
-невозможно логически понять из названия — ставим `TODO`. Обязательно отмечаем 
-какие поля являются опциональными. Пишем заметки по известным значениям полей, 
-чтобы из контекста догадываться о предназначении.
 
-Если добавлен новый файл, то не забудьте сгенерировать `.rst` файл
+Если добавлен новый класс или функция, то не забудьте сгенерировать `.rst` файл выполнив команду `make gen` в папке `docs` и добавить его в GIT.
-выполнив команду `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__`. 
-Добавьте свою модель для короткого импорта в одну из секций `__init__.py` файла
+
-и пропишите название в `__all__`. Обязательно следите за тем, какие поля
+Обязательно следите за тем, какие поля присутствуют всегда, а какие нет. По возможности минимизируйте количество опциональных полей. 
-присутствуют всегда, а какие нет. По возможности минимизируйте количество
+
-опциональных полей. Не забывайте перечислить поля, по которым можно отличить
+Не забывайте перечислить поля, по которым можно отличить один объект от другого в `_id_attrs` (метод `__post_init__`).
-один объект от другого в `_id_attrs` (метод `__post_init__`). Экземпляр класса 
+
-`Client` передаётся в каждую модель для возможности написания методов-сокращений. 
+Экземпляр класса `Client` передаётся в каждую модель для возможности написания методов-сокращений. При наличии дополнительных методов у модели не забудьте создать асинхронную версию метода добавив в название суффикс `_async`. 
-При наличии дополнительных методов у модели не забудьте создать асинхронную версию
+
-метода добавив в название суффикс `_async`. Кроме этого, если у вашей модели 
+Кроме этого, если у вашей модели есть метод, например, `download_async()`, то такому методу следует создать camel case псевдоним (`downloadAsync()`). Для создания псевдонимов существует генератор. Всё что вам надо сделать это поместить в конце файла с моделью маркер:
-есть метод, например, `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 для основного модуля и тестов, сгенерирует асинхронную 
+Выполнит за вас black для основного модуля и тестов, сгенерирует асинхронную версию клиента, сгенерирует camel case псевдонимы.
-версию клиента, сгенерирует camel case псевдонимы.