mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
kolo
ce7e24b924
The entire public api is covered with documentation in two languages - Russian and English. the library now supports the latest three versions of python - 3.12, 3.13 and 3.14 minor design changes: now, when a Boolean flag is entered, its value is an empty string, not None. tests have been adapted to the supported versions of python, readmi has been redesigned in two languages, German is no longer available.
301 lines
19 KiB
ReStructuredText
301 lines
19 KiB
ReStructuredText
.. _root_contributing:
|
||
|
||
Вклад в проект
|
||
==============
|
||
|
||
.. default-role:: code
|
||
|
||
Прежде всего, спасибо, что уделили время для внесения своего вклада! ❤️
|
||
|
||
Мы приветствуем и ценим любой вклад. Пожалуйста, прочтите соответствующий раздел, прежде чем начать. Это облегчит работу мейнтейнеров и сделает процесс более гладким для всех. Сообщество с нетерпением ждёт ваших идей! 🎉
|
||
|
||
.. note::
|
||
|
||
Если вам нравится проект, но у вас нет времени на активный вклад, вы можете поддержать нас другими способами:
|
||
|
||
* Поставить звезду на GitHub.
|
||
* Написать о проекте в Twitter или других социальных сетях.
|
||
* Сослаться на проект в `README` вашего репозитория.
|
||
* Упомянуть проект на митапах и рассказать о нём друзьям и коллегам.
|
||
|
||
.. _contents:
|
||
|
||
Содержание
|
||
----------
|
||
|
||
* :ref:`Кодекс поведения <code-of-conduct>`
|
||
* :ref:`У меня есть вопрос <i-have-a-question>`
|
||
* :ref:`Я хочу внести вклад <i-want-to-contribute>`
|
||
* :ref:`Сообщение об ошибках <reporting-bugs>`
|
||
* :ref:`Предложение улучшений <suggesting-enhancements>`
|
||
* :ref:`Ваш первый вклад в код <your-first-code-contribution>`
|
||
* :ref:`Улучшение документации <improving-documentation>`
|
||
* :ref:`Руководства по стилю <styleguide>`
|
||
* :ref:`Присоединяйтесь к команде проекта <join-the-project-team>`
|
||
|
||
.. _code-of-conduct:
|
||
|
||
Кодекс поведения
|
||
----------------
|
||
|
||
Этот проект и все его участники руководствуются :ref:`Кодексом поведения Argenta <root_code_of_conduct>`.
|
||
Участвуя, вы обязуетесь соблюдать этот кодекс. Пожалуйста, сообщайте о недопустимом поведении.
|
||
|
||
-----
|
||
|
||
.. _i-have-a-question:
|
||
|
||
У меня есть вопрос
|
||
------------------
|
||
|
||
.. note::
|
||
|
||
Прежде чем задать вопрос, пожалуйста, ознакомьтесь с `документацией <https://argenta.readthedocs.io>`_.
|
||
|
||
Поищите ответ в существующих `Issues <https://github.com/koloideal/Argenta/issues>`_. Если вы нашли похожий вопрос, но всё ещё нуждаетесь в разъяснениях, можете написать в нём. Также рекомендуем поискать ответ в интернете.
|
||
|
||
Если ответа не нашлось, создайте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_ и предоставьте как можно больше контекста, включая версии проекта и платформы.
|
||
|
||
Мы займемся вашей задачей как можно скорее.
|
||
|
||
-----
|
||
|
||
.. _i-want-to-contribute:
|
||
|
||
Я хочу внести вклад
|
||
-------------------
|
||
|
||
.. rubric:: Правовое уведомление
|
||
|
||
.. note::
|
||
|
||
Внося вклад в этот проект, вы подтверждаете, что являетесь автором 100% контента, обладаете необходимыми правами на него и соглашаетесь, что он может распространяться под лицензией проекта.
|
||
|
||
.. _reporting-bugs:
|
||
|
||
Сообщение об ошибках
|
||
--------------------
|
||
|
||
.. rubric:: Перед отправкой отчета об ошибке
|
||
|
||
Хороший отчёт об ошибке не должен заставлять других вытягивать из вас дополнительную информацию. Пожалуйста, тщательно всё изучите, соберите информацию и подробно опишите проблему. Это поможет нам исправить её как можно быстрее.
|
||
|
||
* Убедитесь, что вы используете последнюю версию.
|
||
* Убедитесь, что проблема действительно является ошибкой, а не вызвана, например, использованием несовместимых версий окружения. Прочтите `документацию <https://argenta.readthedocs.io>`_ и, если нужна поддержка, загляните в раздел :ref:`У меня есть вопрос <i-have-a-question>`.
|
||
* Проверьте, нет ли уже отчёта о вашей ошибке в `трекере <https://github.com/koloideal/Argenta/issues?q=label%3Abug>`_.
|
||
* Также поищите в интернете (включая `Stack Overflow`), чтобы узнать, обсуждалась ли проблема за пределами `GitHub`.
|
||
* Соберите информацию об ошибке:
|
||
* Трассировка стека.
|
||
* ОС, платформа и версия (Windows, Linux, macOS, x86, ARM).
|
||
* Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера пакетов и т.д.
|
||
* Входные данные и полученный результат.
|
||
* Можете ли вы надёжно воспроизвести проблему? Воспроизводится ли она на старых версиях?
|
||
|
||
.. rubric:: Как мне отправить хороший отчет об ошибке?
|
||
|
||
.. note::
|
||
|
||
Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках с конфиденциальной информацией в публичном трекере. Для этого используйте электронную почту.
|
||
|
||
Мы используем `GitHub Issues` для отслеживания ошибок. Если вы столкнулись с проблемой:
|
||
|
||
* Откройте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_. На этом этапе не нужно присваивать ему метки.
|
||
* Объясните ожидаемое и фактическое поведение.
|
||
* Предоставьте как можно больше контекста и опишите **шаги для воспроизведения**, чтобы проблему можно было воссоздать. Лучше всего изолировать её и создать минимальный тестовый пример.
|
||
* Предоставьте информацию, которую вы собрали в предыдущем разделе.
|
||
|
||
После того, как задача будет создана:
|
||
|
||
* Команда проекта присвоит задаче соответствующую метку.
|
||
* Член команды попытается воспроизвести проблему. Если шагов нет или они не приводят к результату, команда попросит вас предоставить их и пометит задачу как `needs-repro`. Такие задачи не будут рассматриваться до тех пор, пока проблема не будет воспроизведена.
|
||
* Если проблема будет воспроизведена, она будет помечена как `needs-fix` (и, возможно, другими метками, например `critical`), после чего её сможет взять в работу :ref:`любой желающий <your-first-code-contribution>`.
|
||
|
||
-----
|
||
|
||
.. _suggesting-enhancements:
|
||
|
||
Предложение улучшений
|
||
---------------------
|
||
|
||
Этот раздел поможет вам отправить предложение по улучшению `Argenta`, **включая как новые функции, так и незначительные улучшения**. Следование этим рекомендациям поможет мейнтейнерам и сообществу лучше понять вашу идею.
|
||
|
||
.. rubric:: Перед отправкой предложения по улучшению
|
||
|
||
* Убедитесь, что вы используете последнюю версию.
|
||
* Внимательно прочтите `документацию <https://argenta.readthedocs.io>`_ и убедитесь, что предлагаемая функциональность ещё не реализована (возможно, через конфигурацию).
|
||
* Выполните `поиск <https://github.com/koloideal/Argenta/issues>`_, чтобы проверить, не предлагалось ли это улучшение ранее. Если да, добавьте комментарий к существующей задаче.
|
||
* Определите, соответствует ли ваша идея масштабу и целям проекта. Вам предстоит убедительно доказать её пользу. Мы хотим видеть функции, которые будут полезны большинству пользователей. Если ваша идея ориентирована на узкий круг, рассмотрите возможность создания плагина.
|
||
|
||
.. rubric:: Как мне отправить хорошее предложение по улучшению?
|
||
|
||
Предложения по улучшению отслеживаются в `GitHub Issues <https://github.com/koloideal/Argenta/issues>`_.
|
||
|
||
* Используйте **чёткий и описательный заголовок**, чтобы идентифицировать предложение.
|
||
* Предоставьте **пошаговое и подробное описание** предлагаемого улучшения.
|
||
* **Опишите текущее поведение** и **объясните, какое вы ожидали увидеть вместо этого** и почему. Здесь же можно указать, какие альтернативы вам не подходят.
|
||
* **Приложите скриншоты или видео**, которые помогут продемонстрировать шаги или указать на часть, к которой относится предложение.
|
||
* **Объясните, почему это улучшение будет полезно** большинству пользователей `Argenta`. Вы также можете указать на другие проекты, которые решили эту проблему и могут послужить источником вдохновения.
|
||
|
||
-----
|
||
|
||
.. _your-first-code-contribution:
|
||
|
||
Ваш первый вклад в код
|
||
-----------------------
|
||
|
||
Не знаете, с чего начать? Посмотрите на задачи с метками `good first issue` и `help wanted` в нашем репозитории на `GitHub`. Они хорошо подходят для новичков.
|
||
|
||
Чтобы начать, настройте локальное окружение для разработки, следуя этим шагам.
|
||
|
||
#. Сделайте форк репозитория ``Argenta`` на ``GitHub``.
|
||
#. Клонируйте ваш форк на локальную машину:
|
||
|
||
.. code-block:: bash
|
||
|
||
git clone https://github.com/<ВАШ_НИКНЕЙМ>/Argenta.git
|
||
cd Argenta
|
||
|
||
#. Создайте и активируйте виртуальное окружение.
|
||
|
||
.. code-block:: bash
|
||
|
||
# Для macOS/Linux
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
|
||
# Для Windows
|
||
python -m venv .venv
|
||
.venv\Scripts\activate
|
||
|
||
#. Установите зависимости проекта, включая инструменты для разработки.
|
||
|
||
.. code-block:: bash
|
||
|
||
pip install -e .[dev]
|
||
|
||
#. Создайте новую ветку для вашей функции или исправления. Используйте описательное имя, например `fix/login-bug` или `feat/new-widget`.
|
||
|
||
.. code-block:: bash
|
||
|
||
git switch -c your-new-branch-name
|
||
|
||
#. Внесите свои изменения. Напишите код и не забудьте добавить или обновить тесты.
|
||
#. Запустите тесты, чтобы убедиться, что все работает корректно.
|
||
|
||
.. code-block:: bash
|
||
|
||
python -m pytest tests
|
||
|
||
#. Сделайте коммит, следуя :ref:`нашему руководству по стилю <styleguide>`, и отправьте изменения в ваш форк.
|
||
|
||
.. code-block:: bash
|
||
|
||
git add .
|
||
git commit -m "feat(widget): add the new super widget"
|
||
git push origin your-new-branch-name
|
||
|
||
#. Откройте `Pull Request` из вашей ветки в ветку `main` официального репозитория. Предоставьте чёткое описание проблемы и вашего решения. Укажите номер связанной задачи, если она есть.
|
||
|
||
-----
|
||
|
||
.. _improving-documentation:
|
||
|
||
Улучшение документации
|
||
----------------------
|
||
|
||
Хорошая документация крайне важна. Мы используем `Sphinx` для её генерации из исходных файлов в директории `docs/`. Мы приветствуем любые улучшения: от исправления опечатки до написания нового раздела.
|
||
|
||
.. note::
|
||
|
||
Мы поддерживаем документацию на двух языках: русском и английском.
|
||
|
||
.. important::
|
||
|
||
Для инкапсуляции различных команд, необходимых для настройки и запуска проекта мы используем ``just``, он же фигурирует в различных примерах в документации, поэтому рекомендуем вам `установить его <https://github.com/casey/just#installation>`_
|
||
|
||
Для улучшения документации вы можете следовать процессу, похожему на внесение вклада в код:
|
||
|
||
#. Убедитесь, что ваше окружение для разработки настроено, как описано в разделе :ref:`Ваш первый вклад в код <your-first-code-contribution>`.
|
||
#. Перейдите в директорию с документацией.
|
||
|
||
.. code-block:: bash
|
||
|
||
cd docs
|
||
|
||
#. Внесите изменения в **русскую** версию документации (`docs/index.rst` и/или `docs/root/*`).
|
||
#. Чтобы собрать документацию локально в режиме автоматического ребилда и увидеть изменения, выполните:
|
||
|
||
.. code-block:: bash
|
||
|
||
just live-ru
|
||
|
||
#. Откройте `127.0.0.1:8000` в браузере, чтобы просмотреть сгенерированную документацию.
|
||
#. После завершения работы над русской версией необходимо создать английский перевод:
|
||
|
||
.. code-block:: bash
|
||
|
||
just update-langs
|
||
|
||
#. После обновления шаблона обновите файлы перевода, расположенные в `docs/locales/en/LC_MESSAGES/`.
|
||
#. Когда изменения будут готовы, сделайте коммит и откройте `Pull Request`. Используйте префикс `docs:` в сообщении коммита.
|
||
|
||
-----
|
||
|
||
.. _styleguide:
|
||
|
||
Руководства по стилю
|
||
--------------------
|
||
|
||
.. _commits_messages:
|
||
|
||
**Сообщения коммитов**
|
||
|
||
Мы следуем спецификации `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_. Это делает историю проекта более читаемой и позволяет автоматически генерировать журнал изменений.
|
||
|
||
Каждое сообщение коммита состоит из **заголовка**, **тела** и **нижнего колонтитула**.
|
||
|
||
.. code-block:: text
|
||
|
||
<тип>(<область>): <тема>
|
||
|
||
[опциональное тело]
|
||
|
||
[опциональный нижний колонтитул]
|
||
|
||
``<тип>`` должен быть одним из следующих:
|
||
|
||
* **feat**: Новая функция для пользователя.
|
||
* **fix**: Исправление ошибки для пользователя.
|
||
* **docs**: Только изменения в документации.
|
||
* **style**: Изменения, не влияющие на смысл кода (пробелы, форматирование и т.д.).
|
||
* **refactor**: Изменение кода, которое не исправляет ошибку и не добавляет новую функцию.
|
||
* **perf**: Изменение кода, улучшающее производительность.
|
||
* **test**: Добавление недостающих тестов или исправление существующих.
|
||
* **chore**: Изменения в процессе сборки или вспомогательных инструментах и библиотеках.
|
||
|
||
.. rubric:: Примеры
|
||
|
||
Простое исправление:
|
||
``fix: correct typo in user authentication flow``
|
||
|
||
Новая функция с областью видимости:
|
||
``feat(api): add new endpoint for user profiles``
|
||
|
||
-----
|
||
|
||
.. _join-the-project-team:
|
||
|
||
Присоединяйтесь к команде проекта
|
||
---------------------------------
|
||
|
||
Мы всегда ищем энтузиастов для присоединения к команде. Если вы являетесь постоянным участником и продемонстрировали глубокое понимание целей и архитектуры проекта, вы можете стать хорошим кандидатом на роль мейнтейнера.
|
||
|
||
Активные члены сообщества могут стать членами команды. Обычно это включает:
|
||
|
||
* Постоянный вклад в виде качественного кода и документации.
|
||
* Помощь другим пользователям с их вопросами и проблемами.
|
||
* Проверку `Pull Request`'ов от других участников с конструктивной обратной связью.
|
||
|
||
Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ — быть активным и полезным участником сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами.
|
||
|