docs

docs/root/contributing.rst

@@ -7,16 +7,16 @@
 
 Прежде всего, спасибо, что уделили время для внесения своего вклада! ❤️
 
-Мы приветствуем и ценим любые виды вклада. Пожалуйста, прочтите соответствующий раздел, прежде чем делать свой вклад. Это значительно облегчит работу для нас, мейнтейнеров, и сделает процесс более гладким для всех участников. Сообщество с нетерпением ждет ваших вкладов. 🎉
+Мы приветствуем и ценим любой вклад. Пожалуйста, прочтите соответствующий раздел, прежде чем начать. Это облегчит работу мейнтейнеров и сделает процесс более гладким для всех. Сообщество с нетерпением ждёт ваших идей! 🎉
 
 .. note::
 
-   Если вам нравится проект, но у вас просто нет времени на вклад, это нормально. Есть и другие простые способы поддержать проект и выразить свою признательность, которым мы также будем очень рады:
-   
-   * Поставить звезду проекту
-   * Написать о нем в ``Twitter``
-   * Ссылаться на этот проект в ``Readme`` вашего проекта
-   * Упомянуть проект на местных встречах и рассказать о нем друзьям/коллегам
+   Если вам нравится проект, но у вас нет времени на активный вклад, вы можете поддержать нас другими способами:
+
+*   Поставить звезду на GitHub.
+*   Написать о проекте в Twitter или других социальных сетях.
+*   Сослаться на проект в `README` вашего репозитория.
+*   Упомянуть проект на митапах и рассказать о нём друзьям и коллегам.
 
 .. _Содержание:
 
@@ -51,15 +51,11 @@
 
 .. note::
 
-   Если вы хотите задать вопрос, мы предполагаем, что вы уже ознакомились с доступной `Документацией <https://argenta.readthedocs.io>`_.
+   Прежде чем задать вопрос, пожалуйста, ознакомьтесь с `документацией <https://argenta.readthedocs.io>`_.
 
-Прежде чем задать вопрос, лучше всего поискать существующие `Issues <https://github.com/koloideal/Argenta/issues>`_, которые могут вам помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также рекомендуется сначала поискать ответы в интернете.
+Поищите ответ в существующих `Issues <https://github.com/koloideal/Argenta/issues>`_. Если вы нашли похожий вопрос, но всё ещё нуждаетесь в разъяснениях, можете написать в нём. Также рекомендуем поискать ответ в интернете.
 
-Если после этого вы все еще чувствуете необходимость задать вопрос, мы рекомендуем следующее:
-
-* Откройте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_.
-* Предоставьте как можно больше контекста о том, с чем вы столкнулись.
-* Укажите версии проекта и платформы (cpython, pip и т.д.), в зависимости от того, что кажется релевантным.
+Если ответа не нашлось, создайте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_ и предоставьте как можно больше контекста, включая версии проекта и платформы (CPython, pip и т.д.).
 
 Мы займемся вашей задачей как можно скорее.
 
@@ -74,7 +70,7 @@
 
 .. note::
 
-   Внося вклад в этот проект, вы должны согласиться с тем, что вы являетесь автором 100% контента, что у вас есть необходимые права на этот контент, и что предоставленный вами контент может распространяться под лицензией проекта.
+   Внося вклад в этот проект, вы подтверждаете, что являетесь автором 100% контента, обладаете необходимыми правами на него и соглашаетесь, что он может распространяться под лицензией проекта.
 
 .. _Сообщение об ошибках:
 
@@ -83,37 +79,37 @@
 
 .. rubric:: Перед отправкой отчета об ошибке
 
-Хороший отчет об ошибке не должен заставлять других вытягивать из вас дополнительную информацию. Поэтому мы просим вас тщательно все изучить, собрать информацию и подробно описать проблему в своем отчете. Пожалуйста, выполните следующие шаги заранее, чтобы помочь нам исправить любую потенциальную ошибку как можно быстрее.
+Хороший отчёт об ошибке не должен заставлять других вытягивать из вас дополнительную информацию. Пожалуйста, тщательно всё изучите, соберите информацию и подробно опишите проблему. Это поможет нам исправить её как можно быстрее.
 
 * Убедитесь, что вы используете последнюю версию.
-* Определите, действительно ли ваша проблема является ошибкой, а не ошибкой с вашей стороны, например, из-за использования несовместимых компонентов/версий окружения (Убедитесь, что вы прочитали `документацию <https://argenta.readthedocs.io>`_. Если вам нужна поддержка, возможно, стоит заглянуть в раздел `У меня есть вопрос`_).
-* Чтобы увидеть, сталкивались ли другие пользователи (и, возможно, уже решили) с той же проблемой, проверьте, нет ли уже отчета о вашей ошибке в `трекере ошибок <https://github.com/koloideal/Argenta/issues?q=label%3Abug>`_.
-* Также обязательно поищите в интернете (включая ``Stack Overflow``), чтобы узнать, обсуждали ли проблему пользователи за пределами сообщества ``GitHub``.
+* Убедитесь, что проблема действительно является ошибкой, а не вызвана, например, использованием несовместимых версий окружения. Прочтите `документацию <https://argenta.readthedocs.io>`_ и, если нужна поддержка, загляните в раздел `У меня есть вопрос`_.
+* Проверьте, нет ли уже отчёта о вашей ошибке в `трекере <https://github.com/koloideal/Argenta/issues?q=label%3Abug>`_.
+* Также поищите в интернете (включая `Stack Overflow`), чтобы узнать, обсуждалась ли проблема за пределами `GitHub`.
 * Соберите информацию об ошибке:
-    * Трассировка стека
-    * ОС, платформа и версия ``Windows``, ``Linux``, ``macOS``, ``x86``, ``ARM``
-    * Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера пакетов, в зависимости от того, что кажется релевантным.
-    * Возможно, ваши входные данные и результат
-    * Можете ли вы надежно воспроизвести проблему? И можете ли вы воспроизвести ее на старых версиях?
+    *   Трассировка стека.
+*   ОС, платформа и версия (Windows, Linux, macOS, x86, ARM).
+*   Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера пакетов и т.д.
+*   Входные данные и полученный результат.
+*   Можете ли вы надёжно воспроизвести проблему? Воспроизводится ли она на старых версиях?
 
 .. rubric:: Как мне отправить хороший отчет об ошибке?
 
 .. note::
 
-   Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках, содержащих конфиденциальную информацию, в трекере задач или в других публичных местах. Конфиденциальные ошибки должны быть отправлены по электронной почте.
+   Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках с конфиденциальной информацией в публичном трекере. Для этого используйте электронную почту.
 
-Мы используем ``Issues GitHub`` для отслеживания ошибок. Если вы столкнулись с проблемой в проекте:
+Мы используем `GitHub Issues` для отслеживания ошибок. Если вы столкнулись с проблемой:
 
-* Откройте `Issue <https://github.com/koloideal/Argenta/issues/new>`_. (Поскольку на данном этапе мы не можем быть уверены, является ли это ошибкой, мы просим вас пока не говорить об ошибке и не присваивать метку задаче.)
-* Объясните поведение, которое вы ожидали, и фактическое поведение.
-* Пожалуйста, предоставьте как можно больше контекста и опишите *шаги для воспроизведения*, чтобы кто-то другой мог воссоздать проблему самостоятельно. Обычно это включает ваш код. Для хороших отчетов об ошибках следует изолировать проблему и создать сокращенный тестовый пример.
+* Откройте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_. На этом этапе не нужно присваивать ему метки.
+* Объясните ожидаемое и фактическое поведение.
+* Предоставьте как можно больше контекста и опишите **шаги для воспроизведения**, чтобы проблему можно было воссоздать. Лучше всего изолировать её и создать минимальный тестовый пример.
 * Предоставьте информацию, которую вы собрали в предыдущем разделе.
 
 После того, как задача будет создана:
 
 * Команда проекта присвоит задаче соответствующую метку.
-* Член команды попытается воспроизвести проблему по вашим шагам. Если шагов для воспроизведения нет или нет очевидного способа воспроизвести проблему, команда попросит вас предоставить эти шаги и пометит задачу как `needs-repro`. Ошибки с меткой `needs-repro` не будут рассматриваться до тех пор, пока они не будут воспроизведены.
-* Если команда сможет воспроизвести проблему, она будет помечена как `needs-fix`, а также, возможно, другими метками (например, `critical`), и задача будет оставлена для :ref:`реализации кем-либо <Ваш первый вклад в код>`.
+* Член команды попытается воспроизвести проблему. Если шагов нет или они не приводят к результату, команда попросит вас предоставить их и пометит задачу как `needs-repro`. Такие задачи не будут рассматриваться до тех пор, пока проблема не будет воспроизведена.
+* Если проблема будет воспроизведена, она будет помечена как `needs-fix` (и, возможно, другими метками, например `critical`), после чего её сможет взять в работу :ref:`любой желающий <Ваш первый вклад в код>`.
 
 -----
 
@@ -122,24 +118,24 @@
 Предложение улучшений
 ---------------------
 
-Этот раздел поможет вам отправить предложение по улучшению ``Argenta``, **включая совершенно новые функции и незначительные улучшения существующей функциональности**. Следование этим рекомендациям поможет мейнтейнерам и сообществу понять ваше предложение и найти связанные с ним предложения.
+Этот раздел поможет вам отправить предложение по улучшению `Argenta`, **включая как новые функции, так и незначительные улучшения**. Следование этим рекомендациям поможет мейнтейнерам и сообществу лучше понять вашу идею.
 
 .. rubric:: Перед отправкой предложения по улучшению
 
 * Убедитесь, что вы используете последнюю версию.
-* Внимательно прочтите `документацию <https://argenta.readthedocs.io>`_ и выясните, не реализована ли уже данная функциональность, возможно, через индивидуальную конфигурацию.
-* Выполните `поиск <https://github.com/koloideal/Argenta/issues>`_, чтобы проверить, не было ли уже предложено данное улучшение. Если да, добавьте комментарий к существующей задаче вместо создания новой.
-* Определите, соответствует ли ваша идея масштабам и целям проекта. Вам предстоит убедительно доказать разработчикам проекта достоинства этой функции. Помните, что мы хотим видеть функции, которые будут полезны большинству наших пользователей, а не только небольшой их части. Если вы ориентируетесь только на меньшинство пользователей, рассмотрите возможность написания дополнения/плагина.
+* Внимательно прочтите `документацию <https://argenta.readthedocs.io>`_ и убедитесь, что предлагаемая функциональность ещё не реализована (возможно, через конфигурацию).
+* Выполните `поиск <https://github.com/koloideal/Argenta/issues>`_, чтобы проверить, не предлагалось ли это улучшение ранее. Если да, добавьте комментарий к существующей задаче.
+* Определите, соответствует ли ваша идея масштабу и целям проекта. Вам предстоит убедительно доказать её пользу. Мы хотим видеть функции, которые будут полезны большинству пользователей. Если ваша идея ориентирована на узкий круг, рассмотрите возможность создания плагина.
 
 .. rubric:: Как мне отправить хорошее предложение по улучшению?
 
-Предложения по улучшению отслеживаются как `Issues GitHub <https://github.com/koloideal/Argenta/issues>`_.
+Предложения по улучшению отслеживаются в `GitHub Issues <https://github.com/koloideal/Argenta/issues>`_.
 
-* Используйте **четкий и описательный заголовок** для задачи, чтобы идентифицировать предложение.
-* Предоставьте **пошаговое описание предлагаемого улучшения** как можно подробнее.
-* **Опишите текущее поведение** и **объясните, какое поведение вы ожидали увидеть вместо этого** и почему. На этом этапе вы также можете указать, какие альтернативы вам не подходят.
-* Вы можете **включить скриншоты или записи экрана**, которые помогут продемонстрировать шаги или указать на часть, к которой относится предложение.
-* **Объясните, почему это улучшение было бы полезно** большинству пользователей ``Argenta``. Вы также можете указать на другие проекты, которые решили эту проблему лучше и которые могут послужить источником вдохновения.
+* Используйте **чёткий и описательный заголовок**, чтобы идентифицировать предложение.
+* Предоставьте **пошаговое и подробное описание** предлагаемого улучшения.
+* **Опишите текущее поведение** и **объясните, какое вы ожидали увидеть вместо этого** и почему. Здесь же можно указать, какие альтернативы вам не подходят.
+* **Приложите скриншоты или видео**, которые помогут продемонстрировать шаги или указать на часть, к которой относится предложение.
+* **Объясните, почему это улучшение будет полезно** большинству пользователей `Argenta`. Вы также можете указать на другие проекты, которые решили эту проблему и могут послужить источником вдохновения.
 
 -----
 
@@ -148,9 +144,9 @@
 Ваш первый вклад в код
 -----------------------
 
-Не знаете, с чего начать свой вклад в ``Argenta``? Вы можете начать с просмотра задач с метками ``good first issue`` и ``help wanted`` в нашем репозитории на ``GitHub``. Это задачи, которые хорошо подходят для новичков.
+Не знаете, с чего начать? Посмотрите на задачи с метками `good first issue` и `help wanted` в нашем репозитории на `GitHub`. Они хорошо подходят для новичков.
 
-Чтобы начать вносить свой первый вклад в код, пожалуйста, выполните следующие шаги для настройки вашего локального окружения для разработки.
+Чтобы начать, настройте локальное окружение для разработки, следуя этим шагам.
 
 #. Сделайте форк репозитория ``Argenta`` на ``GitHub``.
 #. Клонируйте ваш форк на локальную машину:
@@ -178,20 +174,20 @@
 
       pip install -e .[dev]
 
-#. Создайте новую ветку для вашей новой функции или исправления ошибки. Используйте описательное имя, например ``fix/login-bug`` или ``feat/new-widget``.
+#. Создайте новую ветку для вашей функции или исправления. Используйте описательное имя, например `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
 
@@ -199,7 +195,7 @@
       git commit -m "feat(widget): add the new super widget"
       git push origin your-new-branch-name
 
-#. Откройте ``Pull Request`` из вашей ветки в ветку ``main`` официального репозитория ``Argenta``. Предоставьте четкое описание проблемы и вашего решения. Укажите номер связанной задачи, если это применимо.
+#. Откройте `Pull Request` из вашей ветки в ветку `main` официального репозитория. Предоставьте чёткое описание проблемы и вашего решения. Укажите номер связанной задачи, если она есть.
 
 -----
 
@@ -208,7 +204,7 @@
 Улучшение документации
 ----------------------
 
-Хорошая документация крайне важна для любого проекта. Мы используем ``Sphinx`` для генерации нашей документации из исходных файлов, расположенных в директории ``docs/``. Мы приветствуем любые улучшения, от исправления простой опечатки до написания целого нового раздела.
+Хорошая документация крайне важна. Мы используем `Sphinx` для её генерации из исходных файлов в директории `docs/`. Мы приветствуем любые улучшения: от исправления опечатки до написания нового раздела.
 
 .. note::
 
@@ -223,22 +219,22 @@
 
       cd docs
 
-#. Внесите необходимые изменения в **русскую** версию документации - ``docs/index.rst`` и/или ``docs/root/*``
-#. Чтобы собрать документацию локально и увидеть ваши изменения, выполните:
+#. Внесите изменения в **русскую** версию документации (`docs/index.rst` и/или `docs/root/*`).
+#. Чтобы собрать документацию локально и увидеть изменения, выполните:
 
    .. code-block:: bash
 
       make live-ru
 
-#. Откройте ``127.0.0.1:8000`` в вашем веб-браузере, чтобы просмотреть сгенерированную документацию.
-#. После завершения работы над русской документацией необходимо создать английский перевод:
+#. Откройте `127.0.0.1:8000` в браузере, чтобы просмотреть сгенерированную документацию.
+#. После завершения работы над русской версией необходимо создать английский перевод:
 
    .. code-block:: bash
 
       make update-langs
 
-#. После обновления шаблона перевода, обновите необходимые файлы перевода, расположенные по пути ``docs/locales/en/LC_MESSAGES``.
-#. Когда вы будете довольны своими изменениями, сделайте коммит и откройте ``Pull Request``. Используйте префикс ``docs:`` в сообщении коммита.
+#. После обновления шаблона обновите файлы перевода, расположенные в `docs/locales/en/LC_MESSAGES/`.
+#. Когда изменения будут готовы, сделайте коммит и откройте `Pull Request`. Используйте префикс `docs:` в сообщении коммита.
 
 -----
 
@@ -252,7 +248,7 @@
 Сообщения коммитов
 ~~~~~~~~~~~~~~~~~~
 
-Мы следуем спецификации `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_ для наших сообщений коммитов. Это приводит к более читаемым сообщениям, которые легко отслеживать при просмотре истории проекта, и позволяет автоматически генерировать журнал изменений.
+Мы следуем спецификации `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_. Это делает историю проекта более читаемой и позволяет автоматически генерировать журнал изменений.
 
 Каждое сообщение коммита состоит из **заголовка**, **тела** и **нижнего колонтитула**.
 
@@ -290,13 +286,13 @@
 Присоединяйтесь к команде проекта
 ---------------------------------
 
-Мы всегда ищем энтузиастов и преданных своему делу людей для присоединения к нашей команде проекта. Если вы являетесь постоянным участником и продемонстрировали глубокое понимание целей и архитектуры проекта, вы можете стать хорошим кандидатом на роль мейнтейнера.
+Мы всегда ищем энтузиастов для присоединения к команде. Если вы являетесь постоянным участником и продемонстрировали глубокое понимание целей и архитектуры проекта, вы можете стать хорошим кандидатом на роль мейнтейнера.
 
-Активные члены сообщества могут стать членами команды. Обычно это включает в себя:
+Активные члены сообщества могут стать членами команды. Обычно это включает:
 
-* Постоянный вклад в виде высококачественного кода и документации.
-* Помощь другим пользователям, отвечая на вопросы и разбирая проблемы.
-* Проверку ``Pull Request`` от других участников с конструктивной обратной связью.
+*   Постоянный вклад в виде качественного кода и документации.
+*   Помощь другим пользователям с их вопросами и проблемами.
+*   Проверку `Pull Request`'ов от других участников с конструктивной обратной связью.
 
-Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ начать — это быть активным и полезным членом сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами с приглашением присоединиться к команде.
+Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ — быть активным и полезным участником сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами.