Як Допомогти#

Цей файл описує стиль нашого коду та деяку іншу документацію про внески. Ви повинні прочитати його перед тим, як зробити свій перший внесок.

Також зверніть увагу, що це все лише рекомендації, ви можете використовувати будь-що в окремих випадках, якщо це буде краще, ніж рішення, які ми тут пропонуємо. Однак, ми віддамо перевагу саме цим рекомендаціям, коли будемо розглядати ваш внесок.

Language#

All contributions, all code, all comments, all commits and everything else must be in English.

`make test`#

Цією «чарівною» командою збираються майже всі наші CI. Якщо ви на Windows, спробуйте Chocolatey, щоб запустити make.

Також через конфлікт між pytest-testmon і pytest-cov ми використовуємо опцію --no-cov у pytest, таким чином ми даємо пріоритет pytest-testmon. Якщо ви хочете згенерувати доповідь за допомогою pytest-cov, використайте make test ci=1.

`pre-commit`#

Крім того, ви можете прив’язати make test (плюс деякі додаткові корисні перевірки) до запуску при кожному коміті, так що ви завжди будете впевнені, що CI ніколи не провалиться. Просто запустіть pre-commit install.

Commit naming style#

Every commit must have one small change. We also use the Tim Pope commit message template for commits“ messages.

If you worry about clean git log - just don’t. We use squash strategy for merging PRs.

Стиль Коду#

Ми використовуємо black майже для всього контролю стилів. Ми також намагаємося використовувати форматери замість літерів, де це можливо.

Крім того, у нас також є правила, які black не покриває. До них відносяться:

Імпорти#

Для контролю імпортів у нас є isort та pycln. Перший використовується для сортування імпортів, а другий - для видалення імпортів, що не використовуються. Всі інші правила не покриваються лінтерами/форматерами тощо. Ви повинні перевіряти їх самостійно.

Вам слід використовувати import module і from package import module, коли це можливо, але іноді більш корисним є шлях from module import .... Наприклад:

from dataclasses import dataclass

Якщо ви використовуєте тільки одну змінну з модуля, і добре зрозуміло її сенс без імені цього модуля, то слід використовувати from module import .... Але якщо ви використовуєте багато змінних з модуля, то краще буде import module/from package import module:

from functools import cached_property

Ви могли помітити, що import module і from package import module написані через /. Це тому, що ви повинні використовувати перший підхід, якщо немає пакета (package). Але якщо пакет є - потрібно використовувати from package import module. Подивіться на ці приклади:

import os
from my_project import config
from my_project import models

Зверніть увагу, що тут немає ніякого відносного імпорту, ви не можете його використовувати у нас. Однак ви можете використовувати as.

Також у всіх файлах __init__.py з будь-яким кодом (не одним doc-рядком) необхідно вказувати змінну __all__. Причиною цього обмеження є те, що pycln і документація не можуть точно знати, чи ви хочете додати імпорт як псевдонім, чи цей імпорт призначений для використання в коді, який знаходиться в цьому файлі. pycln проігнорує цей імпорт, а документація продублює документацію для всього, що ви імпортуєте.

Док-рядки#

Ми використовуємо flake8 для перевірки наявності та якості рядків документів. Вони пізніше з’являться в документації API. Ви повинні писати док-рядки всюди, крім методів __init__ (не те саме, що __init__.py файли), тому що вони не потраплять до документації.

Я також рекомендую прочитати гайд по стилю Google про док-рядки, оскільки ми використовуємо стиль Google у док-рядках.

Розмітка#

Через обмеження Sphinx ми вимушені використовувати розмітку ReST у doc-рядках. Це дозволяє нам використовувати перехресні посилання на інші функції або навіть проєкти.

Докладніше про розмітку ReST і перехресні посилання у Sphinx.

Док-рядки у `init.py`#

Вони описують пакет (теку, package) з модулями (.py файлами, modules).

Док-рядки у модулі, функції, класі та методі#

Це короткий опис елемента. Вони повинні відповідати гайду по стилю Google про док-рядки.

Док-рядки у змінних#

Вони повинні бути у форматі:

some_variable = "abc"
"""This ``some`` variable used in :class:`.SomeClass`."""

Це стосується рівня модуля та атрибутів класів у дата-классах/класах, створених за допомогою attrs. Це не буде працювати в методах __init__, оскільки вони насправді не попадають в документацію. Атрибути повинні бути задокументовані у док-рядках класів, у розділі Attributes.

Наразі лінтер це не перевіряє. Краще іноді дивитися, чи все у документації до API дійсно задокументовано.

`pyproject.toml`#

У цьому файлі ми налаштовуємо лише poetry (окрім black, він підтримує для налаштування лише файл pyproject.toml).

Групи#

Починаючи з poetry 1.2 з’явилася нова функція - групи. Вона дозволяє завантажувати тільки ті групи пакунків, які вам знадобляться. У нас є чотири групи - make, tests, docs і github_hooks. Кожна з них відповідає своєю назвою про своє призначення.

make: Всі необхідні залежності для make test.
tests: Всі необхідні залежності для тестів.
docs: Всі необхідні залежності для будування документації.
github_hooks: Всі необхідні залежності для GitHub hooks.

Будь ласка подивіться Керування залежностями у poetry.

Версії#

Всі версії повинні слідувати у форматі X.Y.z (абсолютна версія) або (~X.Y). Останній варіант буде компілюватися у вигляді >=X.Y.0,<X.Y+1.0. Наприклад, ми маємо останню версію для абстрактної залежності 1.2.3, ми повинні вказати версію ~1.2, тоді вона скомпілюється у >=1.2.0,<1.3.0 (приймається будь-яка версія латки (patch) для 1.2, але не 1.3+). Якщо буде випущено 1.3.0 - dependabot створить для цього PR.

Детальніше про Semantic Versions та специфікацію залежностей у poetry.

Переклади#

Якщо ви не володієте мовами, які ми підтримуємо - залиште переклад на нас.

Для оновлення .po файлів використайте make translate, після цього ви можете редагувати .po файли, які можуть бути знайдені як locales/<тег мови>/LC_MESSAGES/messages.po або locale/<тег мови>/LC_MESSAGES/ у документації. Після редагування, для компіляції ви можете запустити ще один раз make translate (або make html у документації).

Для додавання нової мови, використайте pybabel init -i locales/base.pot -l <тег мови> -d locales або sphinx-intl update -l <тег мови> для документації.

P.S. Тег мови це коротке ім’я цієї мови, наприклад en або en_EN. Повний список мов які підтримуються може бути знайдений за допомогою pybabel --list-locales.

Документація#

Ми використовуємо Sphinx для документації та док-рядки для документації API. Наразі тут немає ніяких правил та перевірок, окрім doc8.

Інша допомога#

Ви можете допомогти розповсюдженням слова про цю бібліотеку. Також було б великою допомогою написати маленьку статтю як ви використовуєте цей проєкт. Ви також можете поділитися кращими практиками з нами.