mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
docs
This commit is contained in:
@@ -50,6 +50,7 @@ Argenta нужна для создания приложений, которым
|
||||
:caption: Для разработчиков:
|
||||
|
||||
root/contributing
|
||||
root/code_of_conduct
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
.. _root_code_of_conduct:
|
||||
|
||||
Правила сообщества
|
||||
==========================
|
||||
|
||||
Наше обязательство
|
||||
------------------
|
||||
|
||||
В стремлении создать открытую и приветливую атмосферу, мы, как
|
||||
участники и мейнтейнеры, обязуемся сделать участие в нашем проекте и
|
||||
сообществе свободным от преследований для всех, независимо от возраста, телосложения,
|
||||
инвалидности, этнической принадлежности, половых характеристик, уровня опыта, образования,
|
||||
социально-экономического статуса, национальности, внешности, расы и религии.
|
||||
|
||||
-----
|
||||
|
||||
Наши стандарты
|
||||
--------------
|
||||
|
||||
Примеры поведения, способствующего созданию позитивной среды для нашего
|
||||
сообщества, включают:
|
||||
|
||||
* Проявление эмпатии и доброты по отношению к другим людям.
|
||||
* Уважительное отношение к различным мнениям, точкам зрения и опыту.
|
||||
* Предоставление и тактичное принятие конструктивной обратной связи.
|
||||
* Принятие ответственности, извинения перед теми, кого затронули наши ошибки,
|
||||
и извлечение уроков из этого опыта.
|
||||
* Сосредоточение на том, что лучше не только для нас как отдельных личностей, но и для
|
||||
всего сообщества в целом.
|
||||
|
||||
Примеры недопустимого поведения включают:
|
||||
|
||||
* Троллинг, оскорбительные или уничижительные комментарии, а также личные или политические нападки.
|
||||
* Публичное или частное преследование.
|
||||
* Публикация личной информации других лиц, такой как физический или электронный
|
||||
адрес, без их явного разрешения.
|
||||
* Иное поведение, которое можно обоснованно считать неуместным в
|
||||
профессиональной среде.
|
||||
|
||||
-----
|
||||
|
||||
Наши обязанности
|
||||
----------------
|
||||
|
||||
Мейнтейнеры проекта несут ответственность за разъяснение и обеспечение соблюдения наших стандартов
|
||||
приемлемого поведения и предпримут соответствующие и справедливые корректирующие действия в
|
||||
ответ на любые случаи неприемлемого поведения.
|
||||
|
||||
Мейнтейнеры проекта имеют право и обязанность удалять, редактировать или отклонять
|
||||
комментарии, коммиты, код, правки в вики, задачи и другие вклады, которые
|
||||
не соответствуют настоящему Кодексу поведения, или временно либо навсегда
|
||||
заблокировать любого участника за другое поведение, которое они сочтут
|
||||
неуместным, угрожающим, оскорбительным или вредным.
|
||||
|
||||
-----
|
||||
|
||||
Сфера применения
|
||||
----------------
|
||||
|
||||
Настоящий Кодекс поведения применяется во всех пространствах сообщества, а также когда
|
||||
человек официально представляет сообщество в публичных местах.
|
||||
Примеры представления нашего сообщества включают использование официального адреса электронной почты,
|
||||
публикации через официальный аккаунт в социальных сетях или выступление в качестве назначенного
|
||||
представителя на онлайн- или офлайн-мероприятии.
|
||||
|
||||
-----
|
||||
|
||||
Обеспечение соблюдения
|
||||
----------------------
|
||||
|
||||
О случаях оскорбительного, преследовательского или иного неприемлемого поведения можно
|
||||
сообщить руководителям сообщества, ответственным за обеспечение правоприменения, по адресу .
|
||||
Все жалобы будут рассмотрены и расследованы оперативно и справедливо.
|
||||
|
||||
Все руководители сообщества обязаны уважать частную жизнь и безопасность
|
||||
заявителя любого инцидента.
|
||||
|
||||
-----
|
||||
|
||||
Атрибуция
|
||||
----------
|
||||
|
||||
Настоящий Кодекс поведения адаптирован из `Contributor Covenant <https://www.contributor-covenant.org/>`__, версии
|
||||
`1.4 <https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md>`__ и
|
||||
`2.0 <https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md>`__.
|
||||
|
||||
+297
-4
@@ -1,9 +1,302 @@
|
||||
.. _root_contributing:
|
||||
|
||||
Вклад в проект
|
||||
***************************
|
||||
==============
|
||||
|
||||
``argenta`` открытый проект и мы рады новым разработчикам в нашем сообществе.
|
||||
.. 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`` от других участников с конструктивной обратной связью.
|
||||
|
||||
Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ начать — это быть активным и полезным членом сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами с приглашением присоединиться к команде.
|
||||
|
||||
Getting started
|
||||
========================
|
||||
|
||||
Reference in New Issue
Block a user