.. _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`'ов от других участников с конструктивной обратной связью.

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

