Argenta/docs/root/contributing.rst

.. _root_contributing:

Вклад в проект
==============

.. default-role:: code

Прежде всего, спасибо, что уделили время для внесения своего вклада! ❤️

Мы приветствуем и ценим любые виды вклада. Пожалуйста, прочтите соответствующий раздел, прежде чем делать свой вклад. Это значительно облегчит работу для нас, мейнтейнеров, и сделает процесс более гладким для всех участников. Сообщество с нетерпением ждет ваших вкладов. 🎉

.. note::

   Если вам нравится проект, но у вас просто нет времени на вклад, это нормально. Есть и другие простые способы поддержать проект и выразить свою признательность, которым мы также будем очень рады:
   
   * Поставить звезду проекту
   * Написать о нем в ``Twitter``
   * Ссылаться на этот проект в `Readme` вашего проекта
   * Упомянуть проект на местных встречах и рассказать о нем друзьям/коллегам

.. _Содержание:

Содержание
----------

* `Кодекс поведения`_
* `У меня есть вопрос`_
* `Я хочу внести вклад`_
* `Сообщение об ошибках`_
* `Предложение улучшений`_
* `Ваш первый вклад в код`_
* `Улучшение документации`_
* `Руководства по стилю`_
* `Сообщения коммитов`_
* `Присоединяйтесь к команде проекта`_

.. _Кодекс поведения:

Кодекс поведения
----------------

Этот проект и все его участники руководствуются :ref:`Кодексом поведения Argenta <root_code_of_conduct>`.
Участвуя, вы обязуетесь соблюдать этот кодекс. Пожалуйста, сообщайте о недопустимом поведении.

-----

.. _У меня есть вопрос:

У меня есть вопрос
------------------

.. note::

   Если вы хотите задать вопрос, мы предполагаем, что вы уже ознакомились с доступной `Документацией <https://argenta.readthedocs.io>`_.

Прежде чем задать вопрос, лучше всего поискать существующие `Issue <https://github.com/koloideal/Argenta/issues>`_, которые могут вам помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также рекомендуется сначала поискать ответы в интернете.

Если после этого вы все еще чувствуете необходимость задать вопрос, мы рекомендуем следующее:

* Откройте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_.
* Предоставьте как можно больше контекста о том, с чем вы столкнулись.
* Укажите версии проекта и платформы (cpython, pip и т.д.), в зависимости от того, что кажется релевантным.

Мы займемся вашей задачей как можно скорее.

-----

.. _Я хочу внести вклад:

Я хочу внести вклад
-------------------

.. rubric:: Правовое уведомление

.. note::

   Внося вклад в этот проект, вы должны согласиться с тем, что вы являетесь автором 100% контента, что у вас есть необходимые права на этот контент, и что предоставленный вами контент может распространяться под лицензией проекта.

.. _Сообщение об ошибках:

Сообщение об ошибках
--------------------

.. rubric:: Перед отправкой отчета об ошибке

Хороший отчет об ошибке не должен заставлять других вытягивать из вас дополнительную информацию. Поэтому мы просим вас тщательно все изучить, собрать информацию и подробно описать проблему в своем отчете. Пожалуйста, выполните следующие шаги заранее, чтобы помочь нам исправить любую потенциальную ошибку как можно быстрее.

* Убедитесь, что вы используете последнюю версию.
* Определите, действительно ли ваша проблема является ошибкой, а не ошибкой с вашей стороны, например, из-за использования несовместимых компонентов/версий окружения (Убедитесь, что вы прочитали `документацию <https://argenta.readthedocs.io>`_. Если вам нужна поддержка, возможно, стоит заглянуть в раздел `У меня есть вопрос`_).
* Чтобы увидеть, сталкивались ли другие пользователи (и, возможно, уже решили) с той же проблемой, проверьте, нет ли уже отчета о вашей ошибке в `трекере ошибок <https://github.com/koloideal/Argenta/issues?q=label%3Abug>`_.
* Также обязательно поищите в интернете (включая ``Stack Overflow``), чтобы узнать, обсуждали ли проблему пользователи за пределами сообщества ``GitHub``.
* Соберите информацию об ошибке:
    * Трассировка стека
    * ОС, платформа и версия ``Windows``, ``Linux``, ``macOS``, ``x86``, ``ARM``
    * Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера пакетов, в зависимости от того, что кажется релевантным.
    * Возможно, ваши входные данные и результат
    * Можете ли вы надежно воспроизвести проблему? И можете ли вы воспроизвести ее на старых версиях?

.. rubric:: Как мне отправить хороший отчет об ошибке?

.. note::

   Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках, содержащих конфиденциальную информацию, в трекере задач или в других публичных местах. Конфиденциальные ошибки должны быть отправлены по электронной почте.

Мы используем ``Issues GitHub`` для отслеживания ошибок. Если вы столкнулись с проблемой в проекте:

* Откройте `Issue <https://github.com/koloideal/Argenta/issues/new>`_. (Поскольку на данном этапе мы не можем быть уверены, является ли это ошибкой, мы просим вас пока не говорить об ошибке и не присваивать метку задаче.)
* Объясните поведение, которое вы ожидали, и фактическое поведение.
* Пожалуйста, предоставьте как можно больше контекста и опишите *шаги для воспроизведения*, чтобы кто-то другой мог воссоздать проблему самостоятельно. Обычно это включает ваш код. Для хороших отчетов об ошибках следует изолировать проблему и создать сокращенный тестовый пример.
* Предоставьте информацию, которую вы собрали в предыдущем разделе.

После того, как задача будет создана:

* Команда проекта присвоит задаче соответствующую метку.
* Член команды попытается воспроизвести проблему по вашим шагам. Если шагов для воспроизведения нет или нет очевидного способа воспроизвести проблему, команда попросит вас предоставить эти шаги и пометит задачу как `needs-repro`. Ошибки с меткой `needs-repro` не будут рассматриваться до тех пор, пока они не будут воспроизведены.
* Если команда сможет воспроизвести проблему, она будет помечена как `needs-fix`, а также, возможно, другими метками (например, `critical`), и задача будет оставлена для :ref:`реализации кем-либо <Ваш первый вклад в код>`.

-----

.. _Предложение улучшений:

Предложение улучшений
---------------------

Этот раздел поможет вам отправить предложение по улучшению ``Argenta``, **включая совершенно новые функции и незначительные улучшения существующей функциональности**. Следование этим рекомендациям поможет мейнтейнерам и сообществу понять ваше предложение и найти связанные с ним предложения.

.. rubric:: Перед отправкой предложения по улучшению

* Убедитесь, что вы используете последнюю версию.
* Внимательно прочтите `документацию <https://argenta.readthedocs.io>`_ и выясните, не реализована ли уже данная функциональность, возможно, через индивидуальную конфигурацию.
* Выполните `поиск <https://github.com/koloideal/Argenta/issues>`_, чтобы проверить, не было ли уже предложено данное улучшение. Если да, добавьте комментарий к существующей задаче вместо создания новой.
* Определите, соответствует ли ваша идея масштабам и целям проекта. Вам предстоит убедительно доказать разработчикам проекта достоинства этой функции. Помните, что мы хотим видеть функции, которые будут полезны большинству наших пользователей, а не только небольшой их части. Если вы ориентируетесь только на меньшинство пользователей, рассмотрите возможность написания дополнения/плагина.

.. rubric:: Как мне отправить хорошее предложение по улучшению?

Предложения по улучшению отслеживаются как `Issues GitHub <https://github.com/koloideal/Argenta/issues>`_.

* Используйте **четкий и описательный заголовок** для задачи, чтобы идентифицировать предложение.
* Предоставьте **пошаговое описание предлагаемого улучшения** как можно подробнее.
* **Опишите текущее поведение** и **объясните, какое поведение вы ожидали увидеть вместо этого** и почему. На этом этапе вы также можете указать, какие альтернативы вам не подходят.
* Вы можете **включить скриншоты или записи экрана**, которые помогут продемонстрировать шаги или указать на часть, к которой относится предложение.
* **Объясните, почему это улучшение было бы полезно** большинству пользователей ``Argenta``. Вы также можете указать на другие проекты, которые решили эту проблему лучше и которые могут послужить источником вдохновения.

-----

.. _Ваш первый вклад в код:

Ваш первый вклад в код
-----------------------

Не знаете, с чего начать свой вклад в ``Argenta``? Вы можете начать с просмотра задач с метками ``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

#. Сделайте коммит ваших изменений, следуя нашему руководству по стилю сообщений коммитов, и отправьте их в ваш форк.

   .. 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`` официального репозитория ``Argenta``. Предоставьте четкое описание проблемы и вашего решения. Укажите номер связанной задачи, если это применимо.

-----

.. _Улучшение документации:

Улучшение документации
----------------------

Хорошая документация крайне важна для любого проекта. Мы используем ``Sphinx`` для генерации нашей документации из исходных файлов, расположенных в директории ``docs/``. Мы приветствуем любые улучшения, от исправления простой опечатки до написания целого нового раздела.

.. note::

   Мы поддерживаем документацию на двух языках: русском и английском.

Для улучшения документации вы можете следовать процессу, похожему на внесение вклада в код:

#. Убедитесь, что ваше окружение для разработки настроено, как описано в разделе `Ваш первый вклад в код`_.
#. Перейдите в директорию с документацией.

   .. code-block:: bash

      cd docs

#. Внесите необходимые изменения в **русскую** версию документации - ``docs/index.rst`` и/или ``docs/root/*``
#. Чтобы собрать документацию локально и увидеть ваши изменения, выполните:

   .. code-block:: bash

      make live-ru

#. Откройте ``127.0.0.1:8000`` в вашем веб-браузере, чтобы просмотреть сгенерированную документацию.
#. После завершения работы над русской документацией необходимо создать английский перевод:

   .. code-block:: bash

      make update-langs

#. После обновления шаблона перевода, обновите необходимые файлы перевода, расположенные по пути ``docs/locales/en/LC_MESSAGES``.
#. Когда вы будете довольны своими изменениями, сделайте коммит и откройте ``Pull Request``. Используйте префикс ``docs:`` в сообщении коммита.

-----

.. _Руководства по стилю:

Руководства по стилю
--------------------

.. _Сообщения коммитов:

Сообщения коммитов
~~~~~~~~~~~~~~~~~~

Мы следуем спецификации `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``

-----

.. _Присоединяйтесь к команде проекта:

Присоединяйтесь к команде проекта
---------------------------------

Мы всегда ищем энтузиастов и преданных своему делу людей для присоединения к нашей команде проекта. Если вы являетесь постоянным участником и продемонстрировали глубокое понимание целей и архитектуры проекта, вы можете стать хорошим кандидатом на роль мейнтейнера.

Активные члены сообщества могут стать членами команды. Обычно это включает в себя:

* Постоянный вклад в виде высококачественного кода и документации.
* Помощь другим пользователям, отвечая на вопросы и разбирая проблемы.
* Проверку ``Pull Request`` от других участников с конструктивной обратной связью.

Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ начать — это быть активным и полезным членом сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами с приглашением присоединиться к команде.